Complete email payload

POST /sending/emails accepts all the fields below. Use an API key with emails:send, created in Settings › API keys. For authentication and your first request, start with Send your first email.

A complete direct-content request

The attachment below is a real base64 encoding of a short text file. Replace the addresses with your own and use a domain verified in Settings › Sending domains.

{
  "from": { "email": "orders@example.com", "name": "Example Store" },
  "to": [{ "email": "emma@example.net", "name": "Emma" }],
  "cc": [{ "email": "finance@example.com", "name": "Finance" }],
  "bcc": [{ "email": "archive@example.com" }],
  "replyTo": [{ "email": "support@example.com", "name": "Support" }],
  "subject": "Your order {{orderId}} is confirmed",
  "html": "<p>Hello {{name}},</p><p>Order {{orderId}} is confirmed.</p>",
  "text": "Hello {{name}}, your order {{orderId}} is confirmed.",
  "variables": { "name": "Emma", "orderId": "1042" },
  "attachments": [
    {
      "fileName": "order-1042.txt",
      "content": "T3JkZXIgMTA0Mg==",
      "contentType": "text/plain"
    }
  ],
  "metadata": { "orderId": "1042", "customerId": "cus_89" },
  "tags": { "category": "order-confirmation", "store": "main" },
  "headers": { "X-Order-ID": "1042" },
  "tracking": { "opens": false, "clicks": false }
}

Send a unique Idempotency-Key header with this request. Keep the same key and the same payload for retries. All fields, including attachments, variables, metadata and schedule, participate in conflict detection. Changing a field under a previously accepted key returns 409; changing the order of dictionary entries does not.

Fields and defaults

Field	Format	Behavior when omitted
to	Nonempty list of { email, name? }	Required.
cc, bcc	Lists of mailbox objects	No copy recipients. To, CC and BCC together may contain at most 50 unique addresses.
from	One { email, name? } object	The account’s default sender.
replyTo	1–10 mailbox objects	The saved sender’s reply-to address. These addresses do not receive a delivery.
subject	String, at most 300 characters after substitution	The template’s subject, if templateId is present; otherwise required.
html	String, at most 500,000 characters after substitution	No HTML part, unless supplied by a template.
text	String, at most 500,000 characters after substitution	No explicit plain-text part.
templateId	Saved template UUID	Use the content in this request.
variables	Object of string values	No substitution for direct content; templates require every used variable.
attachments	List of attachment objects	No attachments.
metadata	Object of string values	No correlation data.
tags	Object of string values	No labels.
headers	Object of custom header values	No custom headers.
sendAt	ISO 8601 timestamp with timezone	Eligible for sending immediately.
tracking	{ opens?: boolean, clicks?: boolean }	Account and recipient tracking preferences.

to, cc, bcc and replyTo also accept a single bare address string for compatibility. Arrays contain objects, not strings. A mailbox email is at most 320 characters; its optional display name is at most 100.

Supply at least one of html, text or templateId. Supplying both html and text creates HTML and plain-text alternatives in the same email. A text-only email stays text-only; Azimea does not rewrite its links or add an open pixel. External transports may generate a text alternative from HTML when text is omitted. templateId and html are mutually exclusive. A template request can also include text.

Sender and replies

An explicit from.email must belong to a verified sending domain of your account. Azimea checks it before accepting the request and checks again at delivery. Another account’s domain is not sufficient. from.name overrides the saved sender name for this message. Sender configuration is managed in Settings › Sending.

Omitting from preserves the default-sender behavior: the email can wait in the queue until a verified default is available. replyTo accepts addresses outside the sending domain; they only control where replies go. An empty replyTo list is invalid. Omit the field to inherit the saved reply-to.

Templates and variables

Create a reusable email in Templates and use its UUID:

{
  "to": [{ "email": "emma@example.net", "name": "Emma" }],
  "templateId": "01a10900-0000-7000-8000-000000000401",
  "variables": { "name": "Emma", "orderId": "1042" },
  "metadata": { "orderId": "1042" }
}

Open the saved template to find its UUID at the end of the dashboard URL (/templates/{id}). The UUID must identify a saved template in the same account or sandbox as the API key. A missing or inaccessible template returns 404. The template’s current HTML and subject are copied and rendered when the request is accepted. Later edits or deletion do not change queued messages or an idempotent replay. You can override the subject in the request.

Write placeholders as {{name}} or {{ orderId }} in the subject, HTML or text. Keys are case-sensitive; values must be strings. Every used placeholder needs a value, otherwise the request fails with sending.template_variable_missing before any recipient is queued.

There are at most 100 variables, each value at most 10,000 characters. Keys contain 1–64 ASCII letters, digits, underscores, dots or dashes and start with a letter, digit or underscore. HTML values are escaped automatically; text and subject values are inserted literally. Replacement happens once: a value containing another placeholder is not expanded again. This syntax supports string substitution, without loops, conditionals or raw HTML insertion. Subject control characters and rendered content beyond the limits are rejected.

Files and inline images

Each attachment has:

Field	Rule
fileName	Required, 1–255 characters. No paths, control characters or reserved filename punctuation.
content	Required base64 file content. URLs are not accepted.
contentType	MIME type without parameters, such as application/pdf; defaults to application/octet-stream. Multipart types are invalid.
contentId	Optional unique inline identifier, without angle brackets. 1–127 ASCII letters, digits, underscores, dots, @ or dashes.

Use at most 10 attachments and 5 MiB of decoded file data in total. Base64 increases JSON size; the complete request body must fit within 8 MiB. An oversized body returns 413.

To embed an image, use an attachment with contentType: "image/png" and contentId: "logo", then reference it in HTML as <img src="cid:logo" alt="Store logo">. Supply that image’s actual base64 bytes in content. An inline resource requires HTML or a template. Ordinary attachments omit contentId.

The queue keeps the attachment bytes for retries, including recovery after an SMTP handoff. They follow the transactional message’s content-retention policy. No file is downloaded from a caller-supplied URL.

Correlation data and headers

metadata and tags are internal labels. Both are returned in the submission response and GET /sending/emails/{id}, and included in delivery webhook data when nonempty. They do not become email headers. Use them to associate every recipient’s event with your order, invoice or application event.

Each object accepts at most 20 entries. Keys follow the variable-key rules. Metadata values are strings up to 500 characters; tag values are strings up to 100. Do not put credentials or sensitive documents in these labels: your configured webhook destinations receive them. Content retention removes these values from status responses.

headers accepts at most 20 entries. Allowed names are X-* except the reserved X-Azimea-* prefix, plus In-Reply-To and References for email conversations. Names contain at most 64 ASCII letters, digits or dashes; values at most 998 characters without control characters. Case-insensitive duplicate names are rejected.

Routing, MIME and delivery headers such as From, To, Cc, Bcc, Reply-To, Return-Path, Content-Type and Message-ID are managed by Azimea and cannot be overridden through headers.

Schedule a send

Add sendAt to either a direct-content or template request. Generate a timestamp up to 30 days ahead, for example:

const sendAt = new Date(Date.now() + 60 * 60 * 1000).toISOString();

The timestamp is stored in UTC. Past timestamps are eligible immediately. The response includes sendAt; the status remains Queued until delivery starts. This is a not-before time: caps, missing sender configuration, provider availability and retries can make delivery later. Scheduled sandbox sends follow the same clock.

The payload is fixed when accepted. This endpoint does not reschedule or cancel an existing submission. A new request with a new idempotency key creates another send, even if the recipients and content match.

Control tracking

tracking.opens: false removes Azimea’s open pixel. tracking.clicks: false leaves HTML links unrevised. true or an omitted property uses the account’s policy and the recipient’s choice; it cannot enable tracking for someone who opted out or override tracking disabled in account settings.

Manage the account policy in Settings › Sending. Text-only messages have no open pixel and their plain-text links are not rewritten. These options control Azimea tracking. If an external transport adds its own tracking, configure that separately.

Monitor API emails in the dashboard

Open Reports > API emails to see accepted submissions, recipient deliveries and their latest outcomes. Campaigns, flows and flow tests are excluded. Each workspace has its own report; switch to the sandbox workspace to inspect sandbox activity.

The selected period follows the submission’s acceptance date in your browser’s time zone. An idempotent retry does not add another submission. To, CC and BCC each count as a recipient delivery; scheduled and retrying deliveries are included in the queue count. Delivery rate is confirmed deliveries divided by sent deliveries. Opens and clicks count detected human activity only and depend on tracking being enabled and observable.

Search by recipient, subject, submission ID or an exact metadata.orderId. Filter by delivery status, sender address, template UUID or a tag name and value. Matching one recipient keeps the entire submission visible. Open a submission for its recipients, attempts, failure reasons, metadata and latest 200 events. The filtered history can be exported as CSV, up to 10,000 submissions; narrow the period or filters for a larger history.

Only historical messages with a verifiable API origin appear. Content retention can remove addresses and correlation data from older records. A sender inherited from account settings is recorded when delivery starts; queued messages without an explicit from still show the account default.

Transport and failures

The complete To/CC/BCC delivery model requires SMTP: each recipient gets a separate envelope and retry history while sharing the visible To/CC headers. A multi-recipient request on Resend returns sending.recipient_transport_unsupported before queueing anything. Single-recipient Resend requests support the content, reply addresses, attachments and custom headers; templates and scheduling are resolved inside Azimea.

Validation, sender verification and template rendering finish before any recipient is queued. A valid request can still contain individually suppressed recipients; inspect recipients and follow the response and retry guide.