Send an email
Pipeline: (optional) template render → validate → suppression
check (global + per-tenant + erasure) → persist → enqueue to
sender. edge-api never calls SES directly.
Test mode (test_mode: true or X-Relay-Test: true) simulates
delivery: no SES call, no queue write. Recipient local-parts at
emitd.com drive the simulated outcome: delivered@emitd.com →
sent + delivery event, bounced@emitd.com → failed + bounce event
- auto-suppression,
complained@emitd.com→ sent + complaint event - auto-suppression. Any other address defaults to delivered.
Open and click tracking are per send (track_opens,
track_clicks): off by default on the outbound (transactional)
stream, on by default on broadcast. A pixel and rewritten links
on a receipt or sign-in code hurt inbox placement. Delivery, bounce
and complaint events come from the receiving servers and never
depend on tracking.
bearerAuthAuthorizationBearer <token>API key sent as Authorization: Bearer <key>. Looked up by SHA-256
hash (email_core::sha256_hex) against api_keys.hash; revoked
keys and keys belonging to a suspended tenant are rejected. See the
top-level Authentication section for permission levels.
Idempotency-Key?stringUnique key for safe retries, scoped to the tenant. A replay (same key) returns the original result without sending or consuming quota again.
X-Relay-Test?stringIf "true", simulate delivery without sending (see description).
"true""false"application/json- body
Mirrors email_core::SendRequest. Only from is required for the JSON body to deserialize; validate_send_request additionally requires at least one recipient (across to/cc/bcc), a non-empty subject, and at least one of html_body/text_body — UNLESS template_alias is set, in which case the template supplies subject/body before validation runs.
from*stringSender, as hello@example.com or Example <hello@example.com>. Quote a name with punctuation ("Example, Inc" <hello@example.com>). The domain must be a verified sending domain for the tenant (and match the key's domain scope, if scoped).
to?array<>[]cc?array<>[]bcc?array<>[]reply_to?|emailsubject?stringRequired by validation unless a template supplies it.
length <= 1000html_body?string|nulltext_body?string|nullmessage_stream?stringPostmark-style stream separation.
"outbound""outbound""broadcast"tag?|Legacy single tag; prefer tags.
tags?|nulltemplate_alias?|Server-side template alias to render (see Templates). Renders subject/html_body/text_body before validation.
template_model?|Variables for template_alias rendering.
scheduled_at?|Epoch milliseconds. When in the future, the message is persisted as scheduled and enqueued by a per-minute cron once due.
int64attachments?array<>|At most 10; more is refused with validation_failed (too_many_attachments).
items <= 10headers?|Extra message headers, such as X-Entity-Ref-ID, or In-Reply-To and References to thread a reply. Names are letters, digits and hyphens, values are printable ASCII, and a name and value total at most 996 characters. Headers that say who a message is from, where replies go or how to unsubscribe can't be set here (From, Reply-To, Message-ID, List-Unsubscribe and the like, and any Content-* or X-SES-*). Refused with validation_failed, or 403 policy_violation for a key with guardrails, as a person approving a send wouldn't see them.
properties <= 10test_mode?|Simulate delivery without sending (same effect as the X-Relay-Test header).
track_opens?|Add an open-tracking pixel to the HTML body. Omit it to take the stream default: on for broadcast, off for outbound (transactional). Opens are approximate either way, because some clients fetch every image and others block them.
track_clicks?|Route links in the HTML body through the click-tracking redirect. Omit it to take the stream default: on for broadcast, off for outbound (transactional).
Suppressed, scheduled, test-mode, or idempotent-replay result (not queued for immediate delivery). See SendResult for the possible shapes.
application/json- response
The heterogeneous per-email result shape returned by POST /v1/email (200/202) and as each item of POST /v1/email/batch's data array. Exactly which fields are present depends on status/error.
message_id?stringstatus?string"queued""suppressed""scheduled""sent""failed""pending_approval"approval_id?stringPresent when the key's guardrails held this send for a person to approve.
approval_url?stringPresent when the key's guardrails held this send for a person to approve.
uricode?stringPresent on a per-item policy_violation: which guardrail refused it (e.g. policy_recipient_not_allowed).
message?stringPresent on a per-item policy_violation.
ses_message_id?stringPresent only for test-mode sends (a fake placeholder id).
test_mode?booleanscheduled_at?integerPresent when status is scheduled.
int64reason?stringPresent when suppressed via the cross-tenant blocklist: "global_suppression".
idempotent_replay?booleanTrue when this response is a replay of a previous idempotent request.
error?stringStable error code when this item was rejected (e.g. validation_failed, from_domain_not_verified, template_not_found).
detail?stringalias?stringPresent on template_not_found.
from?stringPresent on from_domain_not_verified.
[key: string]?anycurl -X POST 'https://api.emitd.com/v1/email' \ -H 'Content-Type: application/json' \ -d '{ "from": "hello@example.com", "to": [ "user@example.com" ], "subject": "Welcome to emitd!", "html_body": "<p>Hello!</p>"}'{ "message_id": "string", "status": "queued", "approval_id": "string", "approval_url": "http://example.com", "code": "string", "message": "string", "ses_message_id": "string", "test_mode": true, "scheduled_at": 0, "reason": "string", "idempotent_replay": true, "error": "string", "detail": "string", "alias": "string", "from": "string"}