MyAgentMail
Get started
Knowledge baseInboxes

Drafts & iterative composition

Inboxes

Agents rarely build a message in one shot. Drafts let you persist the in-progress work between turns.

The draft lifecycle

  1. Create with whatever fields you have so far. Partial drafts are fine — to, subject, plain body, html body, reply target, are all optional.
  2. Update on subsequent turns. PATCH is merge-style — omitted fields stay as-is, so the agent can refine one field at a time.
  3. Send when ready. Sending atomically delivers the message and deletes the draft.

When to use drafts

  • Multi-turn composition. The agent researches the recipient, drafts a subject, drafts a body, refines the body, then sends.
  • Human-in-the-loop. The agent produces a draft, a human reviews it in your UI, and clicks send. See the Human-in-the-loop guide.
  • Reply composition. Create a draft with replyToMessageId set. When sent, the message is threaded automatically with the original.
  • Queued sends. Hold a finished draft until a signal fires, then POST to /send.

Worked example

# Turn 1 — start the draft
DRAFT=$(curl -sX POST https://myagentmail.com/v1/inboxes/$ID/drafts \
  -H "X-API-Key: ak_..." -H "Content-Type: application/json" \
  -d '{"to":"[email protected]","subject":"Quick question"}' \
  | jq -r .id)

# Turn 2 — add a body after researching the recipient
curl -X PATCH https://myagentmail.com/v1/inboxes/$ID/drafts/$DRAFT \
  -H "X-API-Key: ak_..." -H "Content-Type: application/json" \
  -d '{"plainBody":"Hey — noticed you joined Acme last month ..."}'

# Turn 3 — send, draft is deleted atomically
curl -X POST https://myagentmail.com/v1/inboxes/$ID/drafts/$DRAFT/send \
  -H "X-API-Key: ak_..."

Drafts vs webhooks

A draft is a server-side staging area. A webhook is a notification fired by the server. They're not alternatives — you'd typically use both together: the agent composes a draft over several turns, then (once sent) a webhook fires to record the sent message in your CRM.