Skip to content
AzimeaDocs
Dashboard

Send your first email

Send a transactional email from your own code in five minutes, and read what Azimea answers.

A transactional email is one your own system asks for, about the person’s own account or order: an order confirmation, an access code, a password link. Azimea queues it, sends it from your domain and tells you what happened to it.

SMTP and API access use scoped keys and your verified sending domain. These are the connection details shown by the demo dashboard.
SMTP and API access use scoped keys and your verified sending domain. These are the connection details shown by the demo dashboard.
  1. A verified sending domain. Unless you supply from, emails go out from your company’s default sender, on a domain you have verified in Settings › Sending domains (see sending and deliverability). Without one, the email is accepted but waits in the queue — it is retried every few minutes and goes out as soon as a domain is verified.
  2. An API key with the emails:send permission, made in Settings › API keys (API keys, responses and limits). To try things without reaching anyone, make the key in a sandbox: its emails land in the sandbox’s inbox.

POST /sending/emails requires to and content: subject (up to 300 characters) with html, text, or both (each up to 500,000 characters). A saved templateId can supply the subject and HTML instead. to, cc and bcc accept arrays of mailbox objects with email and an optional name. Existing integrations may still send a single address string.

For sender overrides, reply addresses, attachments, templates, variables, scheduling, metadata and tracking, see the complete email payload. The examples below keep only the essentials.

These examples use an Idempotency-Key so retrying the same request does not send a second email. Use a new key for each different message; keep the same key when retrying it. See safe retries.

Terminal window
curl https://api.azimea.com/v1/sending/emails \
-H "Authorization: Bearer $AZIMEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-confirmation" \
-d '{
"to": [{ "email": "emma@example.com", "name": "Emma" }],
"subject": "Your order 1042 is confirmed",
"html": "<p>Hi Emma,</p><p>Thank you for your order 1042. We will let you know when it ships.</p>"
}'
{
"to": [{ "email": "emma@example.com", "name": "Emma" }],
"cc": [{ "email": "finance@example.com" }],
"bcc": [{ "email": "archive@example.com" }],
"subject": "Your order 1042 is confirmed",
"html": "<p>Your order 1042 is confirmed.</p>"
}
  • At least one To recipient is required. There may be at most 50 recipients in total across all three lists.
  • Omit cc and bcc when unused, or send empty arrays. Do not send null. Array entries must be objects such as { "email": "emma@example.com" }; an array of strings is not accepted.
  • Put a display name in name, up to 100 characters. email must contain one bare address, up to 320 characters.
  • An address may appear only once, including across different lists. Case and surrounding whitespace do not create a new address.
  • Everyone sees To and CC. BCC addresses are absent from every recipient’s email headers.
  • Each recipient has an independent delivery id, suppression decision, retry, tracking links and quota usage.
  • These lists send copies of the same content with shared visible headers. They are not a batch of personalized emails.

Multiple recipients currently require Azimea’s SMTP transport. A deployment using Resend refuses the request with sending.recipient_transport_unsupported before queuing any recipients. Single-recipient requests remain supported.

{
"isSuccess": true,
"value": {
"id": "01a10900-0000-7000-8000-000000000301",
"status": "Queued",
"reason": null,
"recipients": [{
"id": "01a10900-0000-7000-8000-000000000301",
"email": "emma@example.com",
"name": "Emma",
"kind": "To",
"status": "Queued",
"reason": null
}]
},
"status": 0,
"errors": [],
"fieldErrors": null
}
  • id identifies the submission. For one recipient it is also the delivery id. With several recipients, match each recipients[].id to the delivery webhooks’ message_id; submission_id links them together.
  • value.status is the recipients’ common delivery status, or Mixed when they differ. A new delivery starts as Queued — accepted for sending, not yet delivered — or Suppressed: stopped before sending. The outer status: 0 describes the API operation’s success, not email delivery.
  • reason says why an email was stopped. It starts with the reason’s code (sending.gate_bounced), followed by detail separated by |: read it up to the first |.
  • recipients contains each recipient’s status and reason. The overall status is Mixed when they differ; for example, a bounced address may be suppressed while the other copies are queued.

Use GET /sending/emails/{id} with the submission id and an API key that has emails:read. Create a key with that permission in Settings › API keys. The response has the same shape as the send response, with current statuses. BCC addresses are returned only to the authenticated sending account; they are not added to the email content.

Terminal window
curl https://api.azimea.com/v1/sending/emails/01a10900-0000-7000-8000-000000000301 \
-H "Authorization: Bearer $AZIMEA_API_KEY"

A transactional email does not require marketing consent. Address protections still apply:

reason starts with What it means What you do
sending.gate_bounced The address permanently refused your emails. Ask the person for another address.
sending.gate_complained The person marked one of your emails as spam. Nothing: Azimea will not write to them again.
sending.gate_protected The address is on Azimea’s shared protective list. See address protection; do not retry unchanged.

After it is queued, the email moves through the email statuses: Sent, then Delivered or Bounced.

Use this call only for messages about the person’s own account or order. Newsletters, offers and reminders to buy are marketing: send them as campaigns or flows, which check each person’s consent before sending. A transactional email carries no unsubscribe footer, because there is nothing to unsubscribe from; its links and opens are tracked like any other email’s.

Send an Idempotency-Key header with your own id for this email (an order number, a UUID): up to 150 visible ASCII characters, no spaces. If the call times out and you send it again with the same key, Azimea returns the first message and sends nothing more. The key holds for your whole account, whichever API key sends it, and a second call with the same key returns the same recipient deliveries with their current statuses. For keys first used with recipient-list support, reusing the key with different recipients, names, subject or HTML returns 409 with sending.idempotency_conflict. Keys created before recipient-list support retain the older replay behavior. The key remains reserved while the original queue record exists; ordinary content retention does not release it.

Terminal window
curl https://api.azimea.com/v1/sending/emails \
-H "Authorization: Bearer $AZIMEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001-confirmation" \
-d '{"to": "emma@example.com", "subject": "Your order 1001", "html": "<p>Thanks for your order.</p>"}'

Without the header, each call queues a new email, and a retry after a timeout can send it twice. More in retries.

Response or code What to check Next action
400 · sending.recipient_duplicate The same address appears more than once across To, CC and BCC. Keep it in one list only. Changing letter case does not make it a different address.
400 · validation.too_many The combined recipient count exceeds 50. Reduce the count. Splitting into separate requests changes the visible recipient lists.
400 · sending.recipient_transport_unsupported This deployment cannot preserve multiple-recipient semantics through its configured transport. Contact support about SMTP availability. The rejected request has not queued any recipients.
403 on a status lookup The API key lacks emails:read. Use a key created with that permission; emails:send alone is insufficient.
404 · sending.email_not_found The id is incorrect or belongs to another account. Use the send response’s value.id and a key from the same account or sandbox.
409 · sending.idempotency_conflict The key was already used with different content or recipients. Retry the original payload, or use a new key only for a genuinely new send.

A successful response with Suppressed or Mixed is a recipient outcome, not a rejected request. Inspect value.recipients before retrying: submitting the whole email with a new key can duplicate copies already queued or sent.

In a sandbox, open the inbox and check the subject and content of your message. Keep the returned id to correlate delivery events. For live sending, check your sending status if a queued message is delayed.