Skip to content
AzimeaDocs
Dashboard

Send a transactional email

POST
/sending/emails
curl --request POST \
--url https://api.azimea.com/v1/sending/emails \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: null' \
--data '{ "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", "name": "Archive" } ], "replyTo": [ { "email": "support@example.com", "name": "Support" } ], "subject": "Your order {{orderId}} is confirmed", "html": "<p>Hello {{name}},</p><p>Order {{orderId}} is confirmed.</p><img src=\"cid:store-logo\" alt=\"Store logo\">", "text": "Hello {{name}}, your order {{orderId}} is confirmed.", "variables": { "name": "Emma", "orderId": "1042" }, "attachments": [ { "fileName": "order-1042.txt", "content": "T3JkZXIgMTA0Mg==", "contentType": "text/plain" }, { "fileName": "logo.png", "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=", "contentType": "image/png", "contentId": "store-logo" } ], "metadata": { "orderId": "1042", "customerId": "cus_89" }, "tags": { "category": "order-confirmation", "store": "main" }, "headers": { "X-Order-ID": "1042" }, "sendAt": "2026-10-11T09:00:00Z", "tracking": { "opens": false, "clicks": false } }'

Queues a transactional email with To, CC and BCC recipient lists (at most 50 addresses combined). A single address string remains accepted. To and CC are visible; BCC is never written in recipient headers. Each recipient has its own delivery id, status, suppression decision, retry and quota usage. Choose from on a verified company domain, or omit it to use the default sender; without a verified default, the request is refused. Supports replyTo, HTML and/or text, base64 attachments (including inline contentId), templateId with variables, metadata, tags, safe custom headers, sendAt (up to 30 days ahead), and tracking restrictions. Templates are resolved and rendered at acceptance; subject may be omitted when the template supplies it. At most 10 attachments with 5 MiB decoded combined, and 8 MiB total request size. Bounced, complained and protected addresses are suppressed. This endpoint is not for newsletters. The response id identifies the submission; recipients[].id matches delivery webhooks’ message_id. Mixed means recipients have different statuses. Idempotency-Key (up to 150 visible ASCII characters) deduplicates the whole request across the account; different content under an existing new key returns 409. Paused companies and canceled or expired trial subscriptions return 403 without adding recipients, including retries with an existing key. An exhausted daily or monthly quota returns 429 with resetAt and upgradeUrl in the error parameters; no new delivery is queued unless sendAt is after the reset. Keys created before recipient lists retain their original replay behavior. Without a key, retries create new deliveries. Subject is at most 300 characters and HTML 500,000 characters. Needs emails:send.

Idempotency-Key
string
nullable
Example
null

Choose a complete HTML/text or saved-template example below. Together they cover all 16 payload fields and the nested attachment and tracking options. html and templateId cannot be sent together.

Media typeapplication/json
Any of:
Any of:
object
to
required
One of:
Array<object>
>= 1 items <= 50 items
object
email
required

One bare mailbox address, at most 320 characters. Put a display name in name, not inside this field.

string
0 <= 320 characters
name

Optional display name, at most 100 characters. Control characters are rejected.

string
nullable 0 <= 100 characters
subject
required
string
>= 1 characters
html
required
string
>= 1 characters
from

Optional { email, name? } sender on a verified domain belonging to this account. Omit to use the default sender. Checked at acceptance and delivery.

object
email
required

One bare mailbox address, at most 320 characters. Put a display name in name, not inside this field.

string
0 <= 320 characters
name

Optional display name, at most 100 characters. Control characters are rejected.

string
nullable 0 <= 100 characters
replyTo
One of:
Array<object>
>= 1 items <= 10 items
object
email
required

One bare mailbox address, at most 320 characters. Put a display name in name, not inside this field.

string
0 <= 320 characters
name

Optional display name, at most 100 characters. Control characters are rejected.

string
nullable 0 <= 100 characters
text

Plain-text body, up to 500,000 characters after rendering. Supply html, text, or templateId; both html and text produce multipart/alternative.

string
nullable 0 <= 500000 characters
templateId

Saved template UUID in this account or sandbox. Its current HTML and subject are snapshotted at acceptance. Cannot be combined with html. Subject can override the template subject.

string format: guid
nullable
variables

String values for {{key}} substitutions in subject, HTML and text. Up to 100 keys (1-64 letters, digits, underscore, dot or dash; first character alphanumeric or underscore), values up to 10,000 characters. Missing variables fail. HTML substitutions are escaped; no loops or raw HTML.

object
<= 100 properties
key
additional properties
string
attachments

Up to 10 base64 attachments, at most 5 MiB decoded combined. Entire JSON request is limited to 8 MiB. No remote URLs. Optional contentId embeds a file as an inline MIME resource.

Array<object>
<= 10 items
object
fileName
required

Attachment filename, 1-255 characters; no path separators, control characters or filesystem-reserved punctuation.

string
>= 1 characters <= 255 characters
content
required

Base64 encoded file bytes. At most 5 MiB decoded across all attachments. File URLs are not accepted.

string
>= 1 characters <= 6990508 characters
contentType

MIME media type without parameters, such as application/pdf or image/png. Defaults to application/octet-stream. multipart types are rejected.

string
contentId

Optional unique inline content id (1-127 letters, digits, underscore, dot, @ or dash). Reference as cid:value in HTML; omit angle brackets.

string
nullable <= 127 characters
headers

Up to 20 custom headers: X-* except X-Azimea-*, plus In-Reply-To and References. Names at most 64 ASCII letters, digits or dashes; values at most 998 characters without controls. Case-insensitive duplicates and routing/MIME headers are rejected.

object
<= 20 properties
key
additional properties
string
metadata

Up to 20 string pairs for internal correlation, returned by status and webhooks. Values up to 500 characters; keys follow variables rules. Not added to email headers.

object
<= 20 properties
key
additional properties
string
tags

Up to 20 string labels, returned by status and webhooks. Values up to 100 characters; keys follow variables rules. Not added to email headers.

object
<= 20 properties
key
additional properties
string
sendAt

ISO 8601 timestamp with timezone, at most 30 days ahead. Stored in UTC; past timestamps are due immediately. Delivery can occur later because of queue limits or retries. Not an exact arrival guarantee.

string format: date-time
nullable
tracking

Optional opens/clicks restrictions. false disables that measurement; true or omission follows account and recipient policy and cannot override an opt-out. Plain-text links are not rewritten.

object
opens

False disables the open pixel; true/null follows existing account and recipient policy.

boolean
nullable
clicks

False disables HTML link tracking; true/null follows existing account and recipient policy.

boolean
nullable
cc
One of:
Array<object>
<= 50 items
object
email
required

One bare mailbox address, at most 320 characters. Put a display name in name, not inside this field.

string
0 <= 320 characters
name

Optional display name, at most 100 characters. Control characters are rejected.

string
nullable 0 <= 100 characters
bcc
One of:
Array<object>
<= 50 items
object
email
required

One bare mailbox address, at most 320 characters. Put a display name in name, not inside this field.

string
0 <= 320 characters
name

Optional display name, at most 100 characters. Control characters are rejected.

string
nullable 0 <= 100 characters
not matching
html
required
string
>= 1 characters
templateId
required
string
not matching
html
required
string
>= 1 characters
templateId
required
string
not matching
html
required
string
>= 1 characters
templateId
required
string
Examples

All options for direct content

This example supplies html and text; templateId is intentionally absent. Replace the example addresses and use a verified domain for from.email. Replace sendAt with a timestamp up to 30 days ahead, or omit it to send immediately; a past timestamp sends immediately. The attachment data is a small text file and a one-pixel PNG; replace it with your files. Multiple recipients require SMTP. Send Idempotency-Key as an HTTP header, not a payload field. See field limits and defaults.

{
"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",
"name": "Archive"
}
],
"replyTo": [
{
"email": "support@example.com",
"name": "Support"
}
],
"subject": "Your order {{orderId}} is confirmed",
"html": "<p>Hello {{name}},</p><p>Order {{orderId}} is confirmed.</p><img src=\"cid:store-logo\" alt=\"Store logo\">",
"text": "Hello {{name}}, your order {{orderId}} is confirmed.",
"variables": {
"name": "Emma",
"orderId": "1042"
},
"attachments": [
{
"fileName": "order-1042.txt",
"content": "T3JkZXIgMTA0Mg==",
"contentType": "text/plain"
},
{
"fileName": "logo.png",
"content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=",
"contentType": "image/png",
"contentId": "store-logo"
}
],
"metadata": {
"orderId": "1042",
"customerId": "cus_89"
},
"tags": {
"category": "order-confirmation",
"store": "main"
},
"headers": {
"X-Order-ID": "1042"
},
"sendAt": "2026-10-11T09:00:00Z",
"tracking": {
"opens": false,
"clicks": false
}
}

The message id and its status: Queued, or Suppressed with the reason

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

object
id

The submission id. Use it to retrieve all recipient statuses. For a single recipient it is also the delivery id.

string format: guid
status

The common delivery status, or Mixed when recipients have different statuses. Inspect recipients for the individual outcomes.

string
reason

The common reason when all recipients share one; null otherwise. Inspect recipients[].reason for individual problems.

string
nullable
recipients

All recipient deliveries, including suppressed ones. Each has independent status, retries, tracking and quota usage.

Array<object>
object
id

The delivery id for this recipient. Matches message_id in delivery webhooks.

string format: guid
email

The normalized recipient address. Empty after retention removes personal data.

string
name

The optional recipient display name.

string
nullable
kind

Whether the recipient was requested as To, Cc or Bcc.

string
Allowed values: To Cc Bcc
status

This recipient’s current delivery status. Queued and Sent do not mean Delivered.

string
Allowed values: Queued Sent Failed Suppressed Delivered Bounced HandingOff Accepted Unknown PendingReview
reason

The reason for suppression, waiting or failure, when present.

string
nullable
sendAt

Requested UTC schedule, or null for immediate sends. Queued also covers a future schedule.

string format: date-time
nullable
templateId

The template used at acceptance, if any.

string format: guid
nullable
metadata

Caller correlation data; removed when retention erases message content.

object
key
additional properties
string
tags

Caller labels; removed when retention erases message content.

object
key
additional properties
string
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Example
{
"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": null,
"kind": "To",
"status": "Queued",
"reason": null
}
],
"sendAt": null,
"templateId": null,
"metadata": {},
"tags": {}
},
"status": 0,
"errors": [],
"fieldErrors": null
}

Validation failed: see errors[].code and fieldErrors

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

nullable
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Example
{
"isSuccess": false,
"value": null,
"status": 5,
"errors": [
{
"code": "validation.required",
"message": "Fill in this field.",
"params": null
}
],
"fieldErrors": {
"email": [
{
"code": "validation.required",
"message": "Fill in this field.",
"params": null
}
]
}
}

Missing or invalid API key

The key lacks emails:send, or sending for this company or subscription is stopped

The template does not exist in this account

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

nullable
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Examplegenerated
{
"isSuccess": true,
"value": "example",
"status": 1,
"errors": [
{
"code": "example",
"message": "example",
"params": {
"additionalProperty": "example"
}
}
],
"fieldErrors": {
"additionalProperty": [
{
"code": "example",
"message": "example",
"params": {
"additionalProperty": "example"
}
}
]
}
}

The idempotency key was already used with a different payload

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

nullable
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Examplegenerated
{
"isSuccess": true,
"value": "example",
"status": 1,
"errors": [
{
"code": "example",
"message": "example",
"params": {
"additionalProperty": "example"
}
}
],
"fieldErrors": {
"additionalProperty": [
{
"code": "example",
"message": "example",
"params": {
"additionalProperty": "example"
}
}
]
}
}

The request body exceeds 8 MiB

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

nullable
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Examplegenerated
{
"isSuccess": true,
"value": "example",
"status": 1,
"errors": [
{
"code": "example",
"message": "example",
"params": {
"additionalProperty": "example"
}
}
],
"fieldErrors": {
"additionalProperty": [
{
"code": "example",
"message": "example",
"params": {
"additionalProperty": "example"
}
}
]
}
}

Per-key rate limit or sending quota reached; quota responses include resetAt and upgradeUrl