# 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](/docs/guides/authentication).

## Send a message

[`POST /mailboxes/{mailboxId}/send`](/docs/api/delivery/post_MessageSend)

```bash
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.

```json
{
  "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`](/docs/sdks/typescript/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](/docs/sdks/typescript/errors#retries-and-idempotent-sends)).
