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
- The public API on
api.<base_domain>, called with@email/api-client:client['emails.send']({ body, idempotencyKey })orclient['emails.sendBatch']({ body, idempotencyKey }). - A service principal that carries the tenant:
x-service-auth(REQ-12) yieldsPrincipal { kind: 'service', tenantId, scopes: ['emails:write'], product }. It never carries a user identity, and it gets theservicerate class (per-route classes, REQ-29). - The product-service task role of a producer grants send rights on the producer's own queues only; the emails queues are not reachable from another product by design.
Request
| Field | Rule |
|---|---|
stream_id | A 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). |
from | A verified sending identity of the tenant (domain or address). |
to | Exactly one recipient per message; campaign fan-out is one call (or batch item) per recipient. |
html / text | Already rendered; emails does no templating. Links are rewritten for tracking when the stream tracks clicks. |
unsubscribe.enabled | Defaults to true on the broadcast lane; an explicit false there rejects with aup.missing_unsubscribe. |
tags, metadata | tags 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_at | Optional; 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
| Status | Meaning | Producer behaviour |
|---|---|---|
202 with status: accepted | Queued for dispatch | Store message_id against your entity (one row per recipient) |
202 with status: held | Admission holds (identity pending, quota, paused stream); a release or a rejection arrives as an event | Treat as in progress, never resend |
202 with status: scheduled | Waiting for scheduled_at | Same 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_codes | Refused by policy (per item inside a batch) | Never retry; surface the reason codes |
402 entitlement_required | The tenant's plan lacks emails or the producing product | Never retry; upgrade path |
429 / 503 with Retry-After | Rate class exhausted / dependency down | Back 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.