Skip to Content
Docs

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

PropertyProductionNotes
Base URLhttps://api.emitd.comGlobal edge routing via Cloudflare Workers
MCP Serverhttps://mcp.emitd.com/mcpHosted Model Context Protocol server for AI agents
AuthenticationAuthorization: Bearer <API_KEY>API keys generated in Console → API keys (esk_live_...)
FormatContent-Type: application/jsonJSON request bodies and responses
IdempotencyIdempotency-Key: <key>Optional header for safe network retries
Test ModeX-Relay-Test: true or test_mode: trueSimulates 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"
  }'
202 Accepted Response
{
  "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:

StatusDescriptionWebhook Event
queuedAccepted at the edge and queued for immediate delivery.—
scheduledHeld until scheduled_at timestamp in the future.scheduled
sentDispatched to Amazon SES outbound mail transport agents.sent
deliveredAccepted by recipient mailbox provider (Gmail, Yahoo, Outlook, etc.).delivery
bouncedRejected by receiving mail server (invalid address, mailbox full).bounce
complainedRecipient marked the email as spam in their email client.complaint
suppressedRecipient address is on your suppression list. Skipped without sending.suppressed
failedDelivery failed permanently.failed

HTTP status & error codes

StatusCodeMeaning
200 OKsuccess / suppressedRequest succeeded (or recipient was suppressed).
202 AcceptedqueuedOutbound message accepted and enqueued for delivery.
400 Bad Requestinvalid_jsonMalformed JSON in request body.
401 UnauthorizedunauthorizedMissing, invalid, or revoked API key.
403 Forbiddeninsufficient_scope / policy_violationAPI key lacks required permissions or violated guardrails.
404 Not Foundnot_foundResource does not exist or belongs to another tenant.
409 Conflictconflict / not_editableConflicting state transition (e.g. editing an active broadcast).
422 Unprocessablevalidation_failed / from_domain_not_verifiedPayload failed validation (unverified domain, bad email syntax).
429 Too Many Requestsrate_limit_exceeded / quota_exceededRate limit or 24-hour quota reached. Inspect Retry-After.
5xx Server Errorinternal_errorServer error. Safe to retry with an Idempotency-Key.

Endpoints by category

Email

Send transactional/marketing email, manage scheduled sends.

Messages

Read-only message activity log.

Domains

Read-only sending domains, their verification state and DNS records.

Analytics

Delivery statistics over a rolling window.

Contacts

Marketing contact store (CRUD, batch, CSV import/export).

Audiences

Static contact lists and their membership.

Segments

Saved (and ad-hoc) contact filters.

Suppressions

Per-tenant suppression (do-not-send) list.

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.

Webhooks

Event webhook endpoint registration and replay.

Inbound

Received email (Cloudflare Email Routing) activity.

Attachments

Upload and retrieve email attachments via R2.

Health

Unauthenticated service health check.

Broadcasts

One-off marketing sends to an audience or segment.

Automations

Event-triggered, multi-step marketing workflows.

On this page