Send an email
POST /v1/email — body parameters, multi-language snippets, preheaders, templates, scheduling, attachments, and the response shape.
Queue a message for delivery with POST /v1/email. emitd validates the payload at the edge, checks suppression registries, enforces tenant rate limits, renders server-side templates, and dispatches to AWS SES in milliseconds.
Every valid call returns an immediate 202 Accepted status with a unique message_id.
Quick send example
curl https://api.emitd.com/v1/email \
-H "Authorization: Bearer $EMITD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <notifications@yourdomain.com>",
"to": ["ada@lovelace.io"],
"reply_to": "support@yourdomain.com",
"subject": "Your receipt #4021",
"html_body": "<h1>Thank you for your order!</h1><p>Your payment has processed successfully.</p>",
"text_body": "Thank you for your order! Your payment has processed successfully.",
"message_stream": "outbound",
"tags": { "campaign": "receipts", "order_id": "4021" }
}'Body parameters
| Field | Type | Description |
|---|---|---|
from (required) | string | The sender email address. Must belong to an authenticated domain verified on your account. Formats supported: "you@domain.com" or "Company Name <you@domain.com>". Put a name with punctuation in quotes: "\"Company, Inc\" <you@domain.com>". Names can be in any language, up to 100 characters. |
to (required) | string[] | Array of recipient email addresses. At least one of to, cc, or bcc is required. Up to 50 recipients per request. |
subject (required) | string | Email subject line. Max 1,000 characters. Optional only if a pre-compiled template provides a default subject. |
html_body | string | Full HTML content of the message. Required unless text_body or template_alias is provided. |
text_body | string | Plain-text fallback version. Highly recommended alongside HTML to maximize spam filter deliverability scores. |
reply_to | string | Optional destination email where recipient replies will be directed. |
cc | string[] | Carbon copy recipient addresses. |
bcc | string[] | Blind carbon copy recipient addresses. |
message_stream | string | outbound (default) for transactional messages (password resets, order receipts, OTPs) or broadcast for marketing newsletters. Keeps IP reputation segregated. |
template_alias | string | Server-side template alias (e.g., "welcome-v2"). See Templates. |
template_model | object | JSON key-value dictionary interpolated into the template variables (e.g., { "name": "Ada" }). |
tags | object | Key-value string pairs used to filter message logs, analytics, and webhook dispatch (e.g., { "user_id": "123", "flow": "onboarding" }). |
scheduled_at | integer | Future epoch timestamp in milliseconds (e.g., 1783386190864). The message is held in storage until that moment. |
attachments | object[] | Up to 10 files (10 MB each). Provide inline Base64 content or a pre-uploaded r2_key. See Attachments. |
headers | object | Up to 10 extra headers (e.g., { "X-Entity-Ref-ID": "order-123" }), or In-Reply-To and References to thread a reply. Headers that say who it's from, where replies go or how to unsubscribe are refused, as is any header from a key with guardrails. |
test_mode | boolean | Set to true to simulate delivery without sending out to external networks (identical to passing X-Relay-Test: true). |
Response format & status lifecycle
Every successful send returns an HTTP 202 Accepted response with the unique message_id:
{
"message_id": "msg_2h8Kd0Rk9Qa",
"status": "queued"
}Possible statuses:
| Status | HTTP Code | Meaning |
|---|---|---|
queued | 202 | Normal happy path. Payload passed edge validation and was enqueued for AWS SES dispatch. |
scheduled | 202 | The message contains a future scheduled_at timestamp and is held safely in storage until due. |
suppressed | 200 | Recipient is on your account's suppression list (due to a previous hard bounce or spam complaint). Nothing was dispatched to protect your sender reputation. |
failed | 4xx / 5xx | Immediate validation failure (invalid sender domain, missing required fields, rate limit exceeded). |
Track delivery progression in the Console Activity or subscribe to Webhooks for real-time delivery, open, click, and bounce events.
Preheader text & inbox previews
The preheader (or preview snippet) is the text that appears directly next to or below your subject line in Gmail, Apple Mail, and Outlook. If omitted, mail clients will grab the first words found in your email body (often "View in browser" or "Unsubscribe").
To ensure a clean preheader that doesn't display visually inside the email body, include this snippet at the very top of your html_body:
<div style="display: none; max-height: 0px; overflow: hidden; mso-hide: all;">
Your receipt #4021 is ready to download.
</div>
<!-- Anti-trailing whitespace hack to prevent subsequent text from leaking into the preview -->
<div style="display: none; max-height: 0px; overflow: hidden; mso-hide: all;">
͏ ‌   ­ ͏ ‌   ­
</div>Deliverability best practices
To ensure your messages consistently land in the primary inbox:
- Always provide both
html_bodyandtext_body: Modern spam filters (like SpamAssassin, Gmail, and Microsoft Defender) score multipart messages higher than HTML-only emails. - Turn off tracking for OTPs and password resets: While open and click tracking is vital for marketing newsletters, tracking pixels can cause privacy extensions or strict corporate spam filters to delay mission-critical authentication codes. Use
message_stream: "outbound"for transactional flows. - Use authentic sender domains: Never send from generic domains (
@gmail.comor@yahoo.com). Ensure your custom domain has SPF, DKIM (2048-bit RSA), and DMARC properly aligned. See Deliverability guide. - Honor one-click unsubscribes: All marketing broadcasts require RFC 8058
List-Unsubscribeheaders. emitd injects these automatically on thebroadcastmessage stream.
Check an email before sending
Some mistakes can't be taken back once an email goes out. POST /v1/email/check reads a draft and tells you what's wrong, without sending it. The console has the same check: Check email in the composer.
curl https://api.emitd.com/v1/email/check \
-H "Authorization: Bearer $EMITD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": "Your receipt",
"html_body": "<a href=\"http://localhost:3000/orders/1\">View order</a>"
}'{
"passed": false,
"errors": 1,
"warnings": 0,
"findings": [
{
"code": "local_link",
"severity": "error",
"message": "This link points at a local or private address, so it won't open for recipients.",
"detail": "http://localhost:3000/orders/1"
}
]
}| Severity | Finds |
|---|---|
error | No subject or body, unfilled {{placeholders}}, links and images on a local or private address |
warn | A long subject, HTML over about 102 KB (Gmail clips it), http:// links and images, links with no destination or no domain, images without alt text, data: images, scripts |
info | Common spam-trigger phrasing |
passed is false when anything is an error. It reads the email only: it doesn't fetch your links, so a link to a page that doesn't exist won't be found.
Safe retries with Idempotency-Key
Network failures and server timeouts can cause clients to retry requests. To prevent sending duplicate emails to recipients, pass an Idempotency-Key header with any unique client-generated string:
curl https://api.emitd.com/v1/email \
-H "Authorization: Bearer $EMITD_API_KEY" \
-H "Idempotency-Key: send_order_4021_attempt_1" \
-H "Content-Type: application/json" \
-d '{ ... }'If the request is retried within 24 hours with the same key, emitd returns the original 202 Accepted response without re-dispatching the email. See Idempotency.
Scheduling sends
Pass scheduled_at with an epoch timestamp in milliseconds in the future. The message will be stored in state scheduled and dispatched automatically when due:
curl https://api.emitd.com/v1/email \
-H "Authorization: Bearer $EMITD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <notifications@yourdomain.com>",
"to": ["ada@lovelace.io"],
"subject": "Scheduled announcement",
"html_body": "<p>See you at the keynote!</p>",
"scheduled_at": 1783386190864
}'While the message is still in scheduled state, you can:
- Reschedule:
PATCH /v1/email/{id}with a new timestamp - Cancel:
DELETE /v1/email/{id}
Batch sending
For sending 2 to 100 individual emails in a single HTTP request with independent recipient templates and metadata, use POST /v1/email/batch.
API Recipes & Code Patterns
Production-ready snippets for OTPs, receipts, templates, attachments, and bulk sends.
Batch sending
Send up to 100 emails in a single API call with individualized parameters.
Email templates
Design server-side templates with Handlebars and AI prompts.
Webhooks
Subscribe to delivery, open, click, bounce, and complaint events.
SDKs & CLI
Official SDKs for nine languages generated from the OpenAPI spec, native HTTPS API, and Model Context Protocol (MCP) tooling.
API recipes & code patterns
Ready-to-use code patterns for the eight most common email scenarios — welcome emails, OTPs, invoices with attachments, dynamic templates, scheduled sends, batch delivery, and inbound webhooks.