Skip to Content

Send a message from a mailbox and read the per-recipient result.

Send from a mailbox and OpenEmail assembles the MIME for you. The response carries one result per recipient, because a send to several addresses can partly succeed.

Paths are relative to https://api.open.email/api/v1, and every request carries a bearer credential — see Authentication.

Send a message

POST /mailboxes/{mailboxId}/send

curl -X POST "$API/mailboxes/$MAILBOX_ID/send?save=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "address": "you@example.com" },
    "to": [{ "address": "someone@example.net" }],
    "subject": "Hello from OpenEmail",
    "text": "Sent over HTTP."
  }'

Only from is required, and addresses are objects — { address, name } — not bare strings, everywhere they appear. Send text, html, or both for a multipart message. Attachments are referenced, not inlined: stage the bytes through the uploads endpoint first, then name the blob here.

save=true stores a copy in the sending mailbox.

Reading the result

A 200 does not mean one thing happened. It means every recipient was accepted — which covers delivered, queued, and filtered. A 207 means at least one recipient failed while others succeeded.

{
  "deliveryId": "dlv_...",
  "recipients": [
    { "address": "someone@example.net", "status": "delivered", "error": "" },
    { "address": "broken@example.invalid", "status": "failed", "error": "..." }
  ],
  "sentCopy": "saved",
  "sentThreadId": "thr_..."
}

Always read recipients rather than inferring from the status code — per-address outcomes are the real result. Each status is one of delivered, queued, filtered, or failed.

sentCopy reports what happened to the saved copy: saved, duplicate, or over_quota. A send can succeed while the copy is refused for quota, so it is reported separately rather than failing the send.

Retrying safely

Pass an X-Delivery-Id header and retry with the same value. The retry converges only the recipients that failed — the ones already delivered are not sent again. Without it, a retry after a partial failure re-sends to everyone.

This is also the answer to a 503: sending is temporarily unavailable, and retrying under the same delivery id is safe. A 403 is not retryable — it means this mailbox may not send at all. A recipient it may not send to fails alone, in a 207, its error saying why (recipient_not_permitted, recipient_not_verified).

In the TypeScript SDK

messages.send is POST /mailboxes/{mailboxId}/send. Its deliveryId option is the X-Delivery-Id header, and the SDK makes one when you give none, the same for each of its own retries (retries and idempotent sends).