/api/mail/draft/{id}

PUT

Update an existing email draft with partial or complete changes using JSON Merge Patch.

PUT /api/mail/draft/{id}

Description

The /api/mail/draft/{id} endpoint allows you to update an existing email draft. This endpoint uses JSON Merge Patch (RFC 7396), which means you only need to send the fields you want to update - all other fields will remain unchanged.

JSON Merge Patch

This endpoint follows the JSON Merge Patch standard. You only need to include the fields you want to modify in your request body. Any fields not included will remain unchanged. This makes it easy to update just the subject, body, or recipients without resending the entire draft.

Path Parameters

Parameter Type Required Description
id string Yes 32-character hexadecimal identifier of the draft to update.

Request Body (JSON)

Send a JSON payload with only the fields you want to update. All fields are optional.

Parameter Type Required Description
subject string No Updated email subject line.
body string No Updated email message body.
recipient_ids array of integers No Updated array of recipient user IDs. Replaces the existing recipient list.
cc_ids array of integers No Updated array of CC recipient user IDs. Replaces the existing CC list.

Example Request Body (Partial Update)

{
  "subject": "Updated: Quarterly Report Draft"
}

Example Request Body (Multiple Fields)

{
  "subject": "Updated: Quarterly Report Draft",
  "body": "Dear team,\n\nI've updated the Q4 report with the latest figures...",
  "recipient_ids": [101, 102, 103, 105]
}

Response

Returns a 200 OK response with the updated draft object.

Response Properties

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

Example Response

{
  "status": "updated",
  "draft": {
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "subject": "Updated: Quarterly Report Draft",
    "body": "Dear team,\n\nI've updated the Q4 report with the latest figures...",
    "recipient_ids": [101, 102, 103, 105],
    "cc_ids": [104],
    "created_at": "2025-12-21T10:30:00Z",
    "updated_at": "2025-12-21T14:15:00Z"
  }
}

Try It Out

http://localhost:8080/api/mail/draft/{id}

Examples

JavaScript (fetch)

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

async function updateDraft(draftId, updates) {
    try {
        const response = await fetch(`${API_BASE}/mail/draft/${draftId}`, {
            method: 'PUT',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(updates)
        });

        const result = await response.json();

        if (response.ok) {
            console.log('Draft updated successfully!');
            console.log('Updated draft:', result.draft);
            console.log('Last updated:', result.draft.updated_at);
        } else {
            console.error('Failed to update draft:', result.message);
        }
    } catch (error) {
        console.error('Error updating draft:', error);
    }
}

// Update only the subject
updateDraft('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', {
    subject: 'Updated: Quarterly Report Draft'
});

// Update subject and body
updateDraft('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', {
    subject: 'Updated: Quarterly Report Draft',
    body: 'Dear team,\n\nI\'ve updated the Q4 report...'
});

// Update recipients
updateDraft('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', {
    recipient_ids: [101, 102, 103, 105]
});

cURL

# Update only the subject
curl -X PUT "http://localhost:8080/api/mail/draft/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Updated: Quarterly Report Draft"
  }'

# Update multiple fields
curl -X PUT "http://localhost:8080/api/mail/draft/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Updated: Quarterly Report Draft",
    "body": "Dear team,\n\nI'"'"'ve updated the Q4 report...",
    "recipient_ids": [101, 102, 103, 105]
  }'

Python

import requests
import json

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

def update_draft(draft_id, updates):
    try:
        response = requests.put(
            f'{API_BASE}/mail/draft/{draft_id}',
            headers={'Content-Type': 'application/json'},
            json=updates
        )

        result = response.json()

        if response.ok:
            print('Draft updated successfully!')
            print(f'Updated draft: {result["draft"]}')
            print(f'Last updated: {result["draft"]["updated_at"]}')
        else:
            print(f'Failed to update draft: {result.get("message", "Unknown error")}')

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

# Update only the subject
update_draft('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', {
    'subject': 'Updated: Quarterly Report Draft'
})

# Update subject and body
update_draft('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', {
    'subject': 'Updated: Quarterly Report Draft',
    'body': 'Dear team,\n\nI\'ve updated the Q4 report...'
})

# Update recipients
update_draft('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6', {
    'recipient_ids': [101, 102, 103, 105]
})