Skip to Content
Docs

Send an email

POST
/v1/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.

Authorization

bearerAuth
headerAuthorizationBearer <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.

Header Parameters

Idempotency-Key?string

Unique 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?string

If "true", simulate delivery without sending (see description).

Value in"true""false"

Request Body

application/json
  1. 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*string

Sender, 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<>
Default[]
cc?array<>
Default[]
bcc?array<>
Default[]
reply_to?|
Formatemail
subject?string

Required by validation unless a template supplies it.

Lengthlength <= 1000
html_body?string|null
text_body?string|null
message_stream?string

Postmark-style stream separation.

Default"outbound"
Value in"outbound""broadcast"
tag?|

Legacy single tag; prefer tags.

tags?|null
template_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.

Formatint64
attachments?array<>|

At most 10; more is refused with validation_failed (too_many_attachments).

Itemsitems <= 10
headers?|

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.

Propertiesproperties <= 10
test_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).

Response Body

Suppressed, scheduled, test-mode, or idempotent-replay result (not queued for immediate delivery). See SendResult for the possible shapes.

application/json
  1. 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?string
status?string
Value in"queued""suppressed""scheduled""sent""failed""pending_approval"
approval_id?string

Present when the key's guardrails held this send for a person to approve.

approval_url?string

Present when the key's guardrails held this send for a person to approve.

Formaturi
code?string

Present on a per-item policy_violation: which guardrail refused it (e.g. policy_recipient_not_allowed).

message?string

Present on a per-item policy_violation.

ses_message_id?string

Present only for test-mode sends (a fake placeholder id).

test_mode?boolean
scheduled_at?integer

Present when status is scheduled.

Formatint64
reason?string

Present when suppressed via the cross-tenant blocklist: "global_suppression".

idempotent_replay?boolean

True when this response is a replay of a previous idempotent request.

error?string

Stable error code when this item was rejected (e.g. validation_failed, from_domain_not_verified, template_not_found).

detail?string
alias?string

Present on template_not_found.

from?string

Present on from_domain_not_verified.

[key: string]?any
curl -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>"}'
Example Response
{  "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"}