Sending
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).