Send your first email
Send a transactional email from your own code in five minutes, and read what Azimea answers.
transactional email · send email API · POST /sending/emails · emails:send · emails:read · CC · BCC · multiple recipients · delivery status · order confirmation · password reset email · quickstart · Suppressed · sending.no_verified_sender
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.
Before you start
Section titled “Before you start”
- 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. - An API key with the
emails:sendpermission, 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.
Send it
Section titled “Send it”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.
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>" }'using System.Net.Http.Headers;using System.Net.Http.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://api.azimea.com/v1/") };http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AZIMEA_API_KEY"));http.DefaultRequestHeaders.Add("Idempotency-Key", "order-1042-confirmation");
var response = await http.PostAsJsonAsync("sending/emails", new{ to = new[] { new { 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>"});var body = await response.Content.ReadAsStringAsync();const response = await fetch('https://api.azimea.com/v1/sending/emails', { method: 'POST', headers: { Authorization: `Bearer ${process.env.AZIMEA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'order-1042-confirmation', }, body: JSON.stringify({ 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>', }),});const body = await response.json();$ch = curl_init('https://api.azimea.com/v1/sending/emails');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('AZIMEA_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: order-1042-confirmation', ], CURLOPT_POSTFIELDS => json_encode([ '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>', ]), CURLOPT_RETURNTRANSFER => true,]);$body = json_decode(curl_exec($ch), true);import os, requests
response = requests.post( "https://api.azimea.com/v1/sending/emails", headers={ "Authorization": f"Bearer {os.environ['AZIMEA_API_KEY']}", "Idempotency-Key": "order-1042-confirmation", }, json={ "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>", },)body = response.json()Add copy recipients
Section titled “Add copy recipients”{ "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
ccandbccwhen unused, or send empty arrays. Do not sendnull. 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.emailmust 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.
Understand the response
Section titled “Understand the response”{ "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}ididentifies the submission. For one recipient it is also the delivery id. With several recipients, match eachrecipients[].idto the delivery webhooks’message_id;submission_idlinks them together.value.statusis the recipients’ common delivery status, orMixedwhen they differ. A new delivery starts asQueued— accepted for sending, not yet delivered — orSuppressed: stopped before sending. The outerstatus: 0describes the API operation’s success, not email delivery.reasonsays 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|.recipientscontains each recipient’s status and reason. The overall status isMixedwhen they differ; for example, a bounced address may be suppressed while the other copies are queued.
Check delivery status
Section titled “Check delivery status”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.
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.
Transactional, not marketing
Section titled “Transactional, not marketing”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.
Make retries safe
Section titled “Make retries safe”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.
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.
Resolve a rejected request
Section titled “Resolve a rejected request”| 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.
- Hear back about delivery, bounces and clicks: webhooks.
- Every field and answer:
POST /sending/emailsin the reference.