Save structured message to mailbox
Constructs and saves an email message from structured JSON (headers, body text/HTML, attachments) into a mailbox without sending.
bearerAuthAuthorizationBearer <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: [].
mailboxId*stringMailbox ULID identifier
label?stringTarget label (default INBOX)
flags?stringComma-separated initial flags, e.g. seen,draft
filter?stringWhether to run the mailbox's active Sieve filter (default false)
"true""false"internaldate?|Epoch seconds recorded as receivedAt (default now)
-62135596800 <= value <= 253402300799x-delivery-id?stringOptional client idempotency key to prevent duplicate imports. Stored NAMESPACED as append:<your id> (an append is the mailbox's own side writing its own row, announced as message.imported, not message.new), so the traffic log and the filtered response show that form — retry with your original value.
application/json- body
attachments?array<>items <= 50bcc?array<>items <= 100cc?array<>items <= 100from*headers?Extra headers; structural ones (Content-Type, Date, …) are refused
html?|HTML body; paired with text as multipart/alternative
inReplyTo?|Parent Message-ID, angle-bracketed
length <= 512messageId?|Overrides the generated Message-ID
length <= 998references?array<>items <= 50replyTo?array<>items <= 10subject?|length <= 2000text?|Plain-text body
to?array<>items <= 100Stored (uid + uidValidity answer IMAP APPENDUID), or status:filtered when an opted-in Sieve filter discarded it
application/json- response
blobHash?stringOn a fresh store: the blob SHA-256 (what body caches key on)
duplicate*booleanTrue if message was already delivered previously
flags?array<string>On a fresh store: the flags the row was stored with
keywords?array<string>On a fresh store: the keywords the row was stored with
messageId*stringAssigned message ULID
modseq?integerOn a fresh store: the membership row's MODSEQ in the target label
int64receivedAt?integerOn a fresh store: the INTERNALDATE in epoch seconds
int64size?integerOn a fresh store: the stored size in bytes
int64status*"delivered"Message was successfully delivered and stored
"delivered"threadId*|Assigned conversation thread ULID, or null on duplicate
uid*|Assigned message UID, or null on duplicate
int64uidValidity*|Label UID validity epoch, or null on duplicate
int64curl -X POST 'https://api.open.email/api/v1/mailboxes/string/messages/compose' \
-H 'Content-Type: application/json' \
-d '{
"from": {
"email": "grace@acme.example",
"name": "Grace Hopper"
},
"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"
}
]
}'{
"blobHash": "string",
"duplicate": true,
"flags": [
"string"
],
"keywords": [
"string"
],
"messageId": "string",
"modseq": 0,
"receivedAt": 0,
"size": 0,
"status": "delivered",
"threadId": "string",
"uid": 0,
"uidValidity": 0
}Subscribe to live mailbox change events over… GET
Upgrades to a WebSocket that streams best-effort change signals for this mailbox: message.new (delivery), message.updated / message.expunged / message.restored…
Copy or move messages and conversations into… POST
Stores each message again, from its original bytes, in a folder of another mailbox you can reach, with its flags, keywords and received time. With `move`, each…