Skip to Content

Send a stored draft.

Sends a message already stored in this mailbox as a draft, byte-for-byte as stored: the Bcc header is stripped from the wire copy, the envelope is derived from the message's own Sender/From (return path) and To/Cc/Bcc (recipients), and the draft row itself becomes the Sent copy — no rebuild, no second copy. Every From address must be this mailbox's own. Answers one result per recipient like /send (200 all accepted, 207 mixed). A retryable per-recipient outcome is retried by the server (202, state pending) rather than reported as failed; a replay under the same X-Delivery-Id answers 202 with the submission's own record.

openemail.messages.sendDraft(
  mailboxId: string,
  messageId: string,
  options?: MessagesSendDraftOptions,
): ApiPromise<MessagesSendDraftResult>

It calls POST /mailboxes/{mailboxId}/messages/{messageId}/submit: Send a stored draft in the API reference.

Example

const result = await openemail.messages.sendDraft(mailboxId, messageId)

Arguments

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.
messageIdstringThe draft's message ULID. The path's {messageId}.

Options

The last argument, options, a MessagesSendDraftOptions, takes:

OptionTypeSent asDescription
bouncebooleanquery bounceDeliver a bounce notice (DSN) to this mailbox if relay fails (default true)
deliveryIdstringheader x-delivery-idOptional idempotency key: a replay answers 202 with this submission's own record instead of sending again

Every call also takes signal, timeout, retry and headers, which say how that one call is sent (call options).

Answer

Awaited, it is the API's JSON, MessagesSendDraftResult. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Retries

When a call gives no deliveryId (the x-delivery-id header), the client makes one, the same for each of the call's retries, so it is retried like a read: the API converges on one send. Give your own to make your own retries safe too (retries and idempotent sends).

Errors

StatusWhat it means
400validation_failed, no_recipients, too_many_recipients, invalid_recipients (a To/Cc/Bcc header is not a valid address list, so the envelope cannot be derived — never guessed at), invalid_from (no usable Sender/From), invalid_address (an envelope address contains ASCII controls), ambiguous_sender (more than one Sender/From address, so no return path can be derived), or a malformed X-Delivery-Id
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
403Permanent — sender_not_owned | sender_not_local | sending_disabled (the mailbox, its domain, or its account may not send) | credential_scope (the credential is scoped below send, design D50) | recipient_not_permitted (a recipient of the draft is outside the submitting credential's own allowlist, naming the address) | from_not_owned | from_sending_disabled (an RFC 5322 From address is not this mailbox's to send under)
404not_found (the mailbox or message does not exist, or is not this caller's) or mailbox_gone (the mailbox was torn down mid-submission)
409not_a_draft — the message is not (or no longer) a draft: moved out of Drafts, in Trash, \Draft cleared, or already sent. already_scheduled — a pending schedule holds this draft; cancel it first (carries scheduleId). delivery_id_reused — the delivery ID belongs to another submission mode or its original retry window has expired.
429TEMPORARY — rate_limited (over the daily allowance), sending_paused or from_sending_paused (a reversible hold), all with Retry-After and retryAfterSeconds; retry with the same X-Delivery-Id
503blob_unreadable — the draft's bytes could not be read right now; submission_record_unavailable — the durable admission could not be read or reserved. Retry with the same delivery ID. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

A failed call rejects with a RequestError: its status, and its code, the API's error. Decide on the code: one status covers several.

Types

MessagesSendDraftResult

/** What `messages.sendDraft` answers. */
type MessagesSendDraftResult = SendResult | ScheduledSend

It names these types of the API, each on a page of its own: ScheduledSend, SendResult.