Skip to Content
Docs
Guides

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

FieldTypeDescription
from (required)stringThe 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)stringEmail subject line. Max 1,000 characters. Optional only if a pre-compiled template provides a default subject.
html_bodystringFull HTML content of the message. Required unless text_body or template_alias is provided.
text_bodystringPlain-text fallback version. Highly recommended alongside HTML to maximize spam filter deliverability scores.
reply_tostringOptional destination email where recipient replies will be directed.
ccstring[]Carbon copy recipient addresses.
bccstring[]Blind carbon copy recipient addresses.
message_streamstringoutbound (default) for transactional messages (password resets, order receipts, OTPs) or broadcast for marketing newsletters. Keeps IP reputation segregated.
template_aliasstringServer-side template alias (e.g., "welcome-v2"). See Templates.
template_modelobjectJSON key-value dictionary interpolated into the template variables (e.g., { "name": "Ada" }).
tagsobjectKey-value string pairs used to filter message logs, analytics, and webhook dispatch (e.g., { "user_id": "123", "flow": "onboarding" }).
scheduled_atintegerFuture epoch timestamp in milliseconds (e.g., 1783386190864). The message is held in storage until that moment.
attachmentsobject[]Up to 10 files (10 MB each). Provide inline Base64 content or a pre-uploaded r2_key. See Attachments.
headersobjectUp 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_modebooleanSet 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:

202 Accepted
{
  "message_id": "msg_2h8Kd0Rk9Qa",
  "status": "queued"
}

Possible statuses:

StatusHTTP CodeMeaning
queued202Normal happy path. Payload passed edge validation and was enqueued for AWS SES dispatch.
scheduled202The message contains a future scheduled_at timestamp and is held safely in storage until due.
suppressed200Recipient is on your account's suppression list (due to a previous hard bounce or spam complaint). Nothing was dispatched to protect your sender reputation.
failed4xx / 5xxImmediate 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;">
  &#847; &zwnj; &nbsp; &#8199; &shy; &#847; &zwnj; &nbsp; &#8199; &shy;
</div>

Deliverability best practices

To ensure your messages consistently land in the primary inbox:

  1. Always provide both html_body and text_body: Modern spam filters (like SpamAssassin, Gmail, and Microsoft Defender) score multipart messages higher than HTML-only emails.
  2. 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.
  3. Use authentic sender domains: Never send from generic domains (@gmail.com or @yahoo.com). Ensure your custom domain has SPF, DKIM (2048-bit RSA), and DMARC properly aligned. See Deliverability guide.
  4. Honor one-click unsubscribes: All marketing broadcasts require RFC 8058 List-Unsubscribe headers. emitd injects these automatically on the broadcast message 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"
    }
  ]
}
SeverityFinds
errorNo subject or body, unfilled {{placeholders}}, links and images on a local or private address
warnA 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
infoCommon 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.

On this page