/api/mail/draft

POST

Save a new email draft to your QMail account.

POST /api/mail/draft

Description

The /api/mail/draft endpoint allows you to save an email as a draft without sending it. Drafts can be retrieved later for editing or sending. This is useful for composing emails over time or preparing messages to send later.

Draft Storage

Drafts are stored indefinitely until you delete them or send them as emails. You can access and modify your drafts at any time using the draft update and list endpoints.

Request Body (JSON)

Send a JSON payload with the following structure:

Parameter Type Required Description
subject string Yes Email subject line.
body string Yes Email message body (supports plain text or HTML).
recipient_ids array of integers No Array of recipient user IDs from your contact list.
cc_ids array of integers No Array of CC recipient user IDs from your contact list.

Example Request Body

{
  "subject": "Quarterly Report Draft",
  "body": "Dear team,\n\nI'm working on the Q4 report...",
  "recipient_ids": [101, 102, 103],
  "cc_ids": [104]
}

Response

Returns a 201 Created response with the newly created draft object.

Response Properties

status string
Status of the request (typically "created").
draft object
The created draft object with all details.
draft.id string
Unique 32-character hexadecimal identifier for the draft.
draft.subject string
Email subject line.
draft.body string
Email message body.
draft.recipient_ids array of integers
Array of recipient user IDs.
draft.cc_ids array of integers
Array of CC recipient user IDs.
draft.created_at string
ISO 8601 timestamp when the draft was created.
draft.updated_at string
ISO 8601 timestamp when the draft was last updated.

Example Response

{
  "status": "created",
  "draft": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "subject": "Quarterly Report Draft",
    "body": "Dear team,\n\nI'm working on the Q4 report...",
    "recipient_ids": [101, 102, 103],
    "cc_ids": [104],
    "created_at": "2025-12-21T10:30:00Z",
    "updated_at": "2025-12-21T10:30:00Z"
  }
}

Try It Out

Examples

JavaScript (fetch)

const API_BASE = 'http://localhost:8080/api';

async function saveDraft() {
    const payload = {
        subject: 'Quarterly Report Draft',
        body: 'Dear team,\n\nI\'m working on the Q4 report...',
        recipient_ids: [101, 102, 103],
        cc_ids: [104]
    };

    try {
        const response = await fetch(`${API_BASE}/mail/draft`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        const result = await response.json();

        if (response.ok) {
            console.log('Draft saved successfully!');
            console.log('Draft ID:', result.draft.id);
            console.log('Created at:', result.draft.created_at);
        } else {
            console.error('Failed to save draft:', result.message);
        }
    } catch (error) {
        console.error('Error saving draft:', error);
    }
}

saveDraft();

cURL

curl -X POST "http://localhost:8080/api/mail/draft" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Quarterly Report Draft",
    "body": "Dear team,\n\nI'"'"'m working on the Q4 report...",
    "recipient_ids": [101, 102, 103],
    "cc_ids": [104]
  }'

Python

import requests
import json

API_BASE = 'http://localhost:8080/api'

def save_draft():
    payload = {
        'subject': 'Quarterly Report Draft',
        'body': 'Dear team,\n\nI\'m working on the Q4 report...',
        'recipient_ids': [101, 102, 103],
        'cc_ids': [104]
    }

    try:
        response = requests.post(
            f'{API_BASE}/mail/draft',
            headers={'Content-Type': 'application/json'},
            json=payload
        )

        result = response.json()

        if response.ok:
            print('Draft saved successfully!')
            print(f'Draft ID: {result["draft"]["id"]}')
            print(f'Created at: {result["draft"]["created_at"]}')
        else:
            print(f'Failed to save draft: {result.get("message", "Unknown error")}')

    except Exception as e:
        print(f'Error saving draft: {str(e)}')

save_draft()