Email.com docsOpen the app

Guides

The enqueue contract (for sibling products)

How broadcasts, transactional, sequences (later warmup and sandbox) hand a rendered message to emails. Source of truth: PLAN section 3.6 of the emails product and the emails.send / emails.sendBatch operations of packages/contracts (POST /v1/emails, POST /v1/emails/batch). Nothing else is a supported way in: no shared queue, no direct INSERT, no import of @email/product-emails (A3, D1).

Transport

Request

FieldRule
stream_idA stream of the producing lane: broadcasts and sequences use a broadcast-lane stream, transactional a transactional-lane stream. Test-lane streams route to sandbox-capture and never reach a rail (S21).
source{ product, ref }: the producing product and its entity id (brd_…, seq_…). The policy product of the send is source.product (its entitlement, its quota, its ramp).
fromA verified sending identity of the tenant (domain or address).
toExactly one recipient per message; campaign fan-out is one call (or batch item) per recipient.
html / textAlready rendered; emails does no templating. Links are rewritten for tracking when the stream tracks clicks.
unsubscribe.enabledDefaults to true on the broadcast lane; an explicit false there rejects with aup.missing_unsubscribe.
tags, metadatatags ride on email.accepted.v1 and on reads; metadata is echoed on reads only, never in an event; ids and short words only, never personal data.
scheduled_atOptional; beyond 15 minutes the message waits in a workflow, not in a queue (P5).

Idempotency

Idempotency-Key per message inside a 24 hour window, by convention <product>_<entity_id>_<recipient_hash> (broadcasts_<broadcast_id>_<ctc_id>, transactional_<txm_id>_<hash>); the separator is _ because the core key grammar [A-Za-z0-9_-]{1,255} admits no : (REQ-17, 2026-10-19); batch items carry idempotency_key with the same convention. A replay answers the original 202 body; a different body under the same key answers 409 idempotency_mismatch.

Responses

StatusMeaningProducer behaviour
202 with status: acceptedQueued for dispatchStore message_id against your entity (one row per recipient)
202 with status: heldAdmission holds (identity pending, quota, paused stream); a release or a rejection arrives as an eventTreat as in progress, never resend
202 with status: scheduledWaiting for scheduled_atSame as accepted. emails.cancelMessage works while the row is accepted (a send more than 15 minutes out, waiting in its workflow) or held; a send within 15 minutes is already queued on the retry lane and cancel answers 409
422 policy_rejected with reason_codesRefused by policy (per item inside a batch)Never retry; surface the reason codes
402 entitlement_requiredThe tenant's plan lacks emails or the producing productNever retry; upgrade path
429 / 503 with Retry-AfterRate class exhausted / dependency downBack off as told; never open your own retry loop (P3)

Correlation

email.accepted.v1 carries source and tags; every later email.* event carries message_id and, where a recipient is involved, recipient_hash (never the address, D8). Keep the message_id from the 202; join events on it. Read back through client['emails.getMessage'] and client['emails.listMessageEvents'] with the service principal; never SELECT from core or emails tables (the rows live in the emails schema, ADR 0013 amendment 2026-09-22).

Volume and pacing

At most 100 items per batch call and the send rate class per principal (entitlement send_rps). The API only accepts: the dispatcher paces the rail per tenant lane and per provider account, applies the ramp for young domains, and holds at the provider's day cap until UTC midnight instead of rejecting. A producer that receives 429 backs off; a producer that wants faster delivery asks for entitlement, not for parallel calls.

Lane, routing, events you will see

The stream's lane selects the queue (emails-send-transactional first, emails-send-broadcast for broadcast and test) and the routing policy (mail.send, emails, tenant?, stream?, lane) selects the rail. Expect, per message: email.accepted.v1 (carries scheduled_at when set), then email.queued.v1 (at release for a scheduled send) or email.held.v1, email.sent.v1, then email.delivered.v1 or email.bounced.v1 (bounce_class), email.complained.v1, email.opened.v1 / email.clicked.v1 when tracked, email.unsubscribed.v1 from the one-click and the page. Suppression after a hard bounce, a complaint or an unsubscribe is written by the platform from these events (REQ-13); the next send to that recipient holds or rejects at admission.