Skip to Content
POST
/api/v1/mailboxes/{mailboxId}/send

Sends an email from this mailbox to one or more recipients. The server builds the RFC 5322 MIME message, signs DKIM, applies outbound address list policies, and returns delivery results per recipient. Supports immediate and scheduled sending.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

Query Parameters

save?string

Save a copy to Sent folder (default true)

Value in"true""false"
bounce?string

Deliver a bounce notice (DSN) to this mailbox if relay fails (default true)

Value in"true""false"

Header Parameters

x-delivery-id?string

Optional idempotency key to prevent duplicate sends on network retries. A retry with the same id converges on the original submission instead of sending again, and is not charged against the send allowance a second time. It does not get around a sending hold: while the sender is paused or disabled the retry is refused like any submission (429 sending_paused, 403 sending_disabled), and once the hold lifts it continues at its original charge.

Request Body

application/json
  1. body
attachments?array<>

List of file attachments

Itemsitems <= 50
autoSubmitted?|

RFC 3834 marker for mail an automaton sends: auto-generated (a notification) or auto-replied (an answer to a message). Written as the Auto-Submitted header so a receiver's loop guards recognise it; refused alongside a free-form Auto-Submitted in headers (auto_submitted_conflict)

Value in"auto-generated""auto-replied"
bcc?array<>

Blind carbon copy recipient email addresses (hidden from message headers)

Itemsitems <= 50
cc?array<>

Carbon copy recipient email addresses

Itemsitems <= 50
from*

Sender email address (must belong to this mailbox)

headers?

Additional custom email headers

html?|

HTML body

inReplyTo?|

In-Reply-To Message-ID

Lengthlength <= 512
references?array<>

References header Message-IDs

Itemsitems <= 50
replyTo?array<>

Reply-To email addresses

Itemsitems <= 10
sendAt?|

Release time, epoch seconds. In the future ⇒ the message is stored as a draft and sent then (202 + a schedule); at or before now ⇒ sent immediately. Requires the Sent copy (?save may not be false).

Formatint64
subject?|

Message subject line

Lengthlength <= 2000
text?|

Plain text body

to?array<>

Primary recipient email addresses

Itemsitems <= 50

Response Body

Every recipient was accepted (delivered, queued, or filtered)

application/json
  1. response
deliveryId*string

Master submission delivery ID

recipients*array<>

Outcome status per recipient

sentCopy?string

Status of saving copy to Sent folder ('saved', 'duplicate', 'over_quota')

Value in"saved""duplicate""over_quota"
sentThreadId?|

Conversation thread ID of the saved sent message

Example Request
curl -X POST 'https://api.open.email/api/v1/mailboxes/string/send' \
  -H 'Content-Type: application/json' \
  -d '{
  "attachments": [
    {
      "blobId": "01J9B0B4D7F1H3K6M000000000",
      "contentType": "application/pdf",
      "filename": "q3-report-final.pdf"
    }
  ],
  "from": {
    "email": "grace@acme.example",
    "name": "Grace Hopper"
  },
  "html": "<p>Thanks Ada, final version attached.</p><p>Grace</p>",
  "inReplyTo": "<7f2a1c9e4b8d@mail.example.com>",
  "references": [
    "<7f2a1c9e4b8d@mail.example.com>"
  ],
  "subject": "Re: Q3 report draft",
  "text": "Thanks Ada, final version attached.\n\nGrace",
  "to": [
    {
      "email": "ada@example.com",
      "name": "Ada Lovelace"
    }
  ]
}'
Example Response
{
  "deliveryId": "01J9DVRY2C5E8G1J4M00000000",
  "recipients": [
    {
      "address": "ada@example.com",
      "deliveryId": "01J9DVRY2C5E8G1J4M00000001",
      "status": "queued"
    }
  ],
  "sentCopy": "saved",
  "sentThreadId": "01J9THRD5E8G1J4M7P00000000"
}