guides

Drafts & Labels

Compose email drafts and organise messages with custom labels.

Drafts

Compose messages before sending them. Drafts live in your mailbox until you're ready to send or delete them.

Create a Draft

bash

curl -X POST https://api.nerfmail.com/v1/mailboxes/{mailboxId}/drafts \
  -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Meeting follow-up",
    "textBody": "Here are the notes from today...",
    "htmlBody": "<p>Here are the notes from today...</p>",
    "cc": ["team@example.com"]
  }'

List Drafts

bash

curl "https://api.nerfmail.com/v1/mailboxes/{mailboxId}/drafts?limit=20" \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Update a Draft

bash

curl -X PUT https://api.nerfmail.com/v1/drafts/{draftId} \
  -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Updated: Meeting follow-up",
    "textBody": "Updated notes..."
  }'

Only the fields you include are updated. Everything else stays the same.

Send a Draft

bash

curl -X POST https://api.nerfmail.com/v1/drafts/{draftId}/send \
  -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Idempotency-Key: send-draft-001"

Sending a draft checks the suppression list and rate limits, delivers the email, generates a secure reply token, fires a message.sent webhook, and then deletes the draft.

Delete a Draft

bash

curl -X DELETE https://api.nerfmail.com/v1/drafts/{draftId} \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Labels

Labels give you custom categories for messages and threads. They're scoped to a mailbox.

Create a Label

bash

curl -X POST https://api.nerfmail.com/v1/mailboxes/{mailboxId}/labels \
  -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "important",
    "color": "#ff0000"
  }'

List Labels

bash

curl "https://api.nerfmail.com/v1/mailboxes/{mailboxId}/labels" \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Delete a Label

bash

curl -X DELETE https://api.nerfmail.com/v1/labels/{labelId} \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Deleting a label removes it from all messages and threads.

Apply and Remove Labels

bash

# Apply to a message
curl -X POST https://api.nerfmail.com/v1/messages/{messageId}/labels/{labelId} \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

# Remove from a message
curl -X DELETE https://api.nerfmail.com/v1/messages/{messageId}/labels/{labelId} \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

# Apply to a thread
curl -X POST https://api.nerfmail.com/v1/threads/{threadId}/labels/{labelId} \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

# Remove from a thread
curl -X DELETE https://api.nerfmail.com/v1/threads/{threadId}/labels/{labelId} \
  -H "Authorization: Bearer $MAILBOX_TOKEN"

Auto-Labeling

Nerfmail automatically classifies inbound messages and applies labels prefixed with auto: — for example, auto:finance, auto:travel, auto:social. This happens during processing and doesn't interfere with your custom labels.

PreviousWebhooks

NextSearch & Intelligence