API reference
Every emitd endpoint, generated from the OpenAPI spec, with base URLs, authentication, error models, and lifecycle events.
The emitd API is an edge-native HTTPS REST API powered by Cloudflare Workers and Amazon SES. Requests authenticate with a Bearer API key, payloads are validated at the edge in sub-millisecond time, and outbound messages are queued with sub-second delivery.
API overview & protocol
| Property | Production | Notes |
|---|---|---|
| Base URL | https://api.emitd.com | Global edge routing via Cloudflare Workers |
| MCP Server | https://mcp.emitd.com/mcp | Hosted Model Context Protocol server for AI agents |
| Authentication | Authorization: Bearer <API_KEY> | API keys generated in Console → API keys (esk_live_...) |
| Format | Content-Type: application/json | JSON request bodies and responses |
| Idempotency | Idempotency-Key: <key> | Optional header for safe network retries |
| Test Mode | X-Relay-Test: true or test_mode: true | Simulates delivery without hitting SES |
Canonical send request
curl https://api.emitd.com/v1/email \
-H "Authorization: Bearer $EMITD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "hello@yourdomain.com",
"to": ["user@example.com"],
"subject": "Welcome to our platform",
"html_body": "<h1>Welcome!</h1><p>We are glad to have you.</p>",
"message_stream": "outbound"
}'{
"message_id": "msg_2h8Kd0Rk9Qa",
"status": "queued"
}Message delivery lifecycle
Every email sent through emitd follows an event-driven state machine. Delivery outcomes are streamed in real time to your Webhooks:
| Status | Description | Webhook Event |
|---|---|---|
queued | Accepted at the edge and queued for immediate delivery. | — |
scheduled | Held until scheduled_at timestamp in the future. | scheduled |
sent | Dispatched to Amazon SES outbound mail transport agents. | sent |
delivered | Accepted by recipient mailbox provider (Gmail, Yahoo, Outlook, etc.). | delivery |
bounced | Rejected by receiving mail server (invalid address, mailbox full). | bounce |
complained | Recipient marked the email as spam in their email client. | complaint |
suppressed | Recipient address is on your suppression list. Skipped without sending. | suppressed |
failed | Delivery failed permanently. | failed |
HTTP status & error codes
| Status | Code | Meaning |
|---|---|---|
200 OK | success / suppressed | Request succeeded (or recipient was suppressed). |
202 Accepted | queued | Outbound message accepted and enqueued for delivery. |
400 Bad Request | invalid_json | Malformed JSON in request body. |
401 Unauthorized | unauthorized | Missing, invalid, or revoked API key. |
403 Forbidden | insufficient_scope / policy_violation | API key lacks required permissions or violated guardrails. |
404 Not Found | not_found | Resource does not exist or belongs to another tenant. |
409 Conflict | conflict / not_editable | Conflicting state transition (e.g. editing an active broadcast). |
422 Unprocessable | validation_failed / from_domain_not_verified | Payload failed validation (unverified domain, bad email syntax). |
429 Too Many Requests | rate_limit_exceeded / quota_exceeded | Rate limit or 24-hour quota reached. Inspect Retry-After. |
5xx Server Error | internal_error | Server error. Safe to retry with an Idempotency-Key. |
Endpoints by category
Send transactional/marketing email, manage scheduled sends.
Send an email
Pipeline: (optional) template render → validate → suppression check (global + per-tenant + erasure) → persist → enqueue to `sender`. `edge-api` never…
Check an email before sending
Reads an email for mistakes a send can't take back: links and images on a local address, placeholders nobody filled in, links that go nowhere, images…
Send a batch of emails
Send up to 100 emails in one call. Each is validated and processed independently through the same pipeline as `POST /v1/email`; a per-email result is…
Reschedule a queued or scheduled send
Requires `Action::Manage` (a `full_access` key) — not available to a `sending_access` key.
Cancel a queued or scheduled send
Requires `Action::Manage` (a `full_access` key).
List simulated events for test-mode sends
Events generated by `test_mode`/`X-Relay-Test` sends only (joined against `messages.test_mode = 1`). Cursor is the bare epoch-ms `created_at` of the…
Messages
Read-only message activity log.
List message activity
Newest-first, cursor is the bare epoch-ms `created_at` of the last row returned (`?cursor=` returns rows strictly older). Tag filtering uses D1 `json…
Get message detail
Find out why an address did or didn't get your email
Starts from the recipient, because that's what a support ticket gives you. Reads your suppression list and your 5 most recent messages to the address…
Domains
Read-only sending domains, their verification state and DNS records.
List sending domains
The workspace's sending domains with their verification state and the DNS records to publish. Read-only: add and verify domains in the console.
Get a sending domain
Analytics
Delivery statistics over a rolling window.
Delivery statistics
Sends, delivery outcomes and engagement over the last `days` UTC days, today included. `sent` counts emails handed to the mail server. Test-mode traf…
Usage against your limits
How much of its limits the workspace has used, read from the same counters that refuse a send. `day` is the last 24 hours and `month` the last 30 day…
List API calls
This workspace's API calls, newest first: method, path, status, timing and the key that made each one. No request or response bodies are kept. Calls…
Contacts
Marketing contact store (CRUD, batch, CSV import/export).
List contacts
Newest-first keyset page over `(created_at, id)`.
Create or upsert a contact
Upserts by normalized (lowercased/trimmed) email. Enforces the plan's `max_contacts` cap, but only when the email does not already exist — re-identif…
Get a contact
Update a contact
`attributes` is a merge (incoming keys overlay existing; keys not present are kept) — not a replace. `status` changes only affect marketing eligibili…
Delete a contact
Hard delete. Also removes the contact's audience memberships.
Upsert up to 100 contacts
Each item is validated/upserted independently — a bad item is a per-item failure, not a whole-batch rejection. The plan cap is checked once up front…
Start an async CSV contact import
Uploads the CSV to R2 and inserts a `pending` job; a per-minute cron parses and upserts it in bounded batches (`IMPORT_BATCH` = 500 data rows/tick) s…
Get a contact import job's status
Start an async GDPR contact export
Exports the caller's own tenant's contacts as CSV. `Action::Read` (not `Manage`) — exporting your own data is a read. A per-minute cron builds the CS…
Get a contact export job's status
Download a finished contact export
Streams the CSV from R2. Returns 404 (never 403) if the job doesn't exist, isn't owned by the caller's tenant, or isn't `done` yet — an export id nev…
Audiences
Static contact lists and their membership.
List audiences
Newest-first keyset page over `(created_at, id)`.
Create an audience
Creates an empty static contact list.
Get an audience
Rename or redescribe an audience
Fields omitted from the body keep their current value.
Delete an audience
Hard delete, including all membership rows.
List an audience's members
Oldest-first keyset page over `(created_at, id)` of the member contacts.
Add one contact to an audience
Idempotent — re-adding an existing member is a no-op (200), not an error. On a genuine add, enrolls the contact into any active `audience_added`-trig…
Add up to 100 contacts to an audience
Same idempotent-add + automation-enrollment behavior as the single-member endpoint, tallied into a summary. A `contact_id` not owned by the tenant is…
Remove a contact from an audience
Idempotent — removing a non-member (or an already-removed one) still returns 200 `deleted:true`.
Segments
Saved (and ad-hoc) contact filters.
List segments
Newest-first keyset page over `(created_at, id)`.
Create a saved segment
`filter` is validated by `email_core::parse_filter` and stored as submitted; it is re-validated and re-compiled to SQL on every `preview`/`count`/bro…
Preview an ad-hoc filter without saving it
Compiles `filter` and returns its live count plus a first page of matching contacts — powers a live segment builder while the user is still editing.
Get a segment
Rename or replace a segment's filter
Fields omitted from the body keep their current value; a replacement `filter` is re-validated.
Delete a segment
Preview a saved segment's matching contacts
Oldest-first keyset page over `(created_at, id)` of contacts matching the segment's compiled filter.
Get a saved segment's live match count
Suppressions
Per-tenant suppression (do-not-send) list.
List suppressions
Newest-first; cursor is the bare epoch-ms `created_at` of the last row returned.
Add a suppression
API-added suppressions are always stored as `reason: "manual"` — any `reason` supplied in the body is ignored (`hard_bounce`/ `complaint`/`unsubscrib…
Add up to 100 suppressions
Remove up to 100 suppressions
Uses the JSON-body-with-DELETE pattern.
Remove a suppression
Always returns 200 `deleted:true` regardless of whether the email was actually suppressed — this endpoint does not check existence first.
Validation
Check an email address before you collect or send to it — syntax, DNS, bounce history, and risk signals (role, disposable, random-looking), with a ty…
Templates
Server-side rendered templates with immutable versions.
List templates
Returns the tenant's full set of templates, newest first. Not paginated.
Create a template
Creates the template shell only — call `POST /v1/templates/{alias}/versions` to give it renderable content. `alias` must be unique per tenant.
Get a template and its versions
Update a template's name, description, or variables
Renames, re-describes, or changes the variable contract of a template. The alias is immutable — live integrations send against it. Omitted fields kee…
Delete a template and every version
Removes the template and all its versions. The alias becomes reusable immediately; sends that still use it start failing.
Render a template without sending
Runs the same substitution a send runs. Returns the rendered subject and bodies, the required variables the model is missing, and deliverability warn…
Create a new template version
Each call creates a new immutable version. When `activate` (default `true`), every other version is deactivated first — `POST /v1/email`'s `template_…
Make an existing version the live one
Rolls back (or forward) to any existing version without publishing new content. Sends using the alias render this version immediately. A key with gua…
Webhooks
Event webhook endpoint registration and replay.
List webhook endpoints
Returns the tenant's full set (not paginated). Note: unlike the creation response, each item's `secret` is always an empty string here (the list quer…
Create a webhook endpoint
`secret` (an HMAC-SHA256 signing key, `whsec_...`) is generated server-side and returned **only in this response** — it is never shown again (subsequ…
Delete a webhook endpoint
Always returns 200 `deleted:true`; does not check existence first.
Replay webhook deliveries
Re-executes up to the 50 most recent matching deliveries, recording each as a new `webhook_deliveries` row (never mutates the original).
Inbound
Received email (Cloudflare Email Routing) activity.
List received email
Messages received via Cloudflare Email Routing. Newest-first; cursor is the bare epoch-ms `created_at` of the last row returned. Note the `from_addr`…
Get a received message, including raw MIME
The raw message is returned byte-for-byte from R2 exactly as ingested (never parsed) — `raw` is `null` if the R2 object is missing (metadata is still…
Attachments
Upload and retrieve email attachments via R2.
Upload an attachment
Uploads a file to R2 under `{tenant_id}/{message_id}/{filename}`. Returns an `r2_key` to reference in a `SendRequest`'s `attachments[].r2_key`. `mess…
Download an attachment
Not under `/v1` — a tenant-scoped convenience endpoint, not a public CDN. Requires an API key whose tenant matches the object key's `{tenant_id}/...`…
Health
Unauthenticated service health check.
Broadcasts
One-off marketing sends to an audience or segment.
List broadcasts
Newest-first keyset page over `(created_at, id)`.
Create a draft broadcast
`name` is the only required field — everything else can be filled in later via `PATCH` while still a `draft`. `target_kind`/ `target_id` must be supp…
Get a broadcast
Edit a draft broadcast
Only allowed while `status = draft` (else 409 `not_editable`) — editing a scheduled/sending/finished broadcast out from under the fan-out cron would…
Delete a broadcast
Hard delete, tenant-scoped. No status restriction — this can delete a broadcast in any state.
Validate and send (or schedule) a draft broadcast
Only callable from `draft` (else 409 `not_draft`). Requires a non-empty subject, a non-empty `body_html` or `body_text`, a postal address in the work…
Cancel a draft or scheduled broadcast
`draft`/`scheduled` → `cancelled`. Any other status (already `sending`/`paused`/`sent`/`cancelled`) is a 409 `not_cancelable` — including the race wh…
Automations
Event-triggered, multi-step marketing workflows.
List automations
Newest-first keyset page over `(created_at, id)`.
Create a draft automation
`name` + a valid `trigger_kind` are required; everything else can be filled in via `PATCH` before activation. `steps` (default `[]`) is validated by…
Get an automation
Edit a draft automation
Only allowed while `status = draft` (else 409 `not_editable`) — editing a live program out from under in-flight enrollments would be unsafe. Fields o…
Delete an automation
Hard delete the automation and its enrollments.
Activate an automation
`draft`/`paused` → `active`. Requires a non-empty, valid step program, a valid trigger, and a verified `from_domain_id` (send steps need a verified m…
Pause an active automation
`active` → `paused`. In-flight enrollments are held (not cancelled) — reactivating resumes them where they parked.
Archive an automation
Terminal. Any non-archived status → `archived`, and every still-active enrollment is cancelled in the same call.
Manually enroll a contact
The automation must be `active`. Idempotent — `UNIQUE(automation_id, contact_id)` makes re-enrolling a no-op (200), a genuine enrollment is 201. A ke…