Drafts

Drafts let an agent prepare a message without sending it, for human review or for scheduled sending with send_at.

A draft is an unsent message stored in an inbox. Use drafts when an agent should prepare a reply but a person (or another check) should review it first, or when a message should go out later.

Sending a draft turns it into a normal outbound message, deletes the draft and emits draft.sent.

Creating a draft

curl

curl https://api.machinemail.dev/v0/inboxes/support-agent@machinemail.dev/drafts \ 
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ 
  -H "Content-Type: application/json" \ 
  -d '{\n    "to": ["ada@example.com"],\n    "subject": "Your refund",\n    "text": "Hi Ada, the refund is on its way.",\n    "in_reply_to": "msg_01m4fy8han0000y3ge3m73vw3w"\n  }'

TypeScript

const inbox = encodeURIComponent('support-agent@machinemail.dev');
const res = await fetch(`https://api.machinemail.dev/v0/inboxes/${inbox}/drafts`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MACHINEMAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: ['ada@example.com'],
    subject: 'Your refund',
    text: 'Hi Ada, the refund is on its way.',
    in_reply_to: 'msg_01m4fy8han0000y3ge3m73vw3w',
  }),
});
const draft = await res.json();

Python

import os, requests

draft = requests.post(
    "https://api.machinemail.dev/v0/inboxes/support-agent@machinemail.dev/drafts",
    headers={"Authorization": f"Bearer {os.environ['MACHINEMAIL_API_KEY']}"},
    json={
        "to": ["ada@example.com"],
        "subject": "Your refund",
        "text": "Hi Ada, the refund is on its way.",
        "in_reply_to": "msg_01m4fy8han0000y3ge3m73vw3w",
    },
).json()

{
  "draft_id": "drf_01m4fy8hmj00004yb08pa27yt2",
  "inbox_id": "support-agent@machinemail.dev",
  "pod_id": "pod_01m4fy8h150000w4xty1ehfnqa",
  "labels": [],
  "to": ["ada@example.com"],
  "subject": "Your refund",
  "preview": "Hi Ada, the refund is on its way.",
  "text": "Hi Ada, the refund is on its way.",
  "in_reply_to": "msg_01m4fy8han0000y3ge3m73vw3w",
  "references": ["abc123@example.com"],
  "created_at": "2026-10-09T09:00:16.402Z",
  "updated_at": "2026-10-09T09:00:16.402Z"
}

Reviewing, editing and sending

PATCH accepts to, cc, bcc, subject, text, html, reply_to and send_at, plus add_labels / remove_labels and add_attachments / remove_attachments (attachment IDs). in_reply_to is fixed at creation.

POST .../send sends immediately and returns the same { message_id, thread_id, timestamp } as a normal send. The draft is deleted.

A human-in-the-loop setup gives the agent a key with draft_create but not message_send, message_reply or draft_send, and lets a person review drafts in the dashboard.

Scheduled sending

Set send_at to send the draft automatically. The draft gets send_status: "scheduled", and MachineMail sends it within a few seconds after send_at passes.

{
  "draft_id": "drf_01m4fy8hmj00004yb08pa27yt2",
  "subject": "Later",
  "send_status": "scheduled",
  "send_at": "2026-10-10T09:00:00.000Z"
}

To cancel a schedule, PATCH with "send_at": null. To reschedule, PATCH a new send_at. An edit or a reschedule that lands while the draft is about to go out wins: the draft goes out as edited, or at the new time. A failed draft is not retried automatically.