Skip to main content
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.drafts.send(
  "dft_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);
{
  "id": "dft_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "status": "scheduled",
  "send_at": "2026-10-04T12:00:00.000Z"
}

Send a draft

Sends a draft immediately, or schedules it when the request body supplies a future send_at.
POST/v1/drafts/{id}/sendscope · send
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.drafts.send(
  "dft_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);
{
  "id": "dft_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "status": "scheduled",
  "send_at": "2026-10-04T12:00:00.000Z"
}

Path Parameters

idstringrequired

Draft id.

Body Parameters

send_atstring

Send the draft at this time instead of now: an ISO 8601 UTC time ending in Z, in the future (400 invalid_field otherwise). Left out, the draft is sent at once.

Headers

If-Matchstring

The draft's updated_at as you last read it. Refuses the send if the draft has changed since.

Idempotency-Keystring

Replays the stored response for a repeated key (kept 24 hours), so a retried request never double-sends; the replay carries Idempotent-Replay: true. An error is kept on the key only once the mail has gone out, so a replayed error means it was sent. Once a scheduled send is stored, a failure after that keeps the message's answer on the key instead: the retry answers with the message (201) and raises its message.scheduled if the first request did not. After a failure before either, the same key sends again, as it does after a batch that stored no message and sent no mail. An Idempotency-Key used again with a different body, or on a different route, is refused with invalid_idempotency_key. Only credentials of the same mode, bound to the same agent or to none, share a key: for any other, the same key is a new request.

A draft with no to is refused (400 missing_field, param to), and so is one with a file still uploading or a forwarded file that can no longer be read (409 invalid_field, param attachments). The draft's files go with it, and their bytes are deleted once the mail has left. With If-Match set to the updated_at you last read, a draft that changed since answers 409 duplicate_resource, param updated_at, and nothing goes. A test key cannot send or schedule a draft a live key made (403 live_mode_required), and a live key cannot send or schedule a reply to test mail (403 test_mode_required).

Was this page helpful?