Send a transactional email
A transactional email goes out one at a time, when your system decides: an order confirmation, a receipt, an access code. It is billed at the same rate as your campaigns and counts toward the same limit.
Keep this API for messages that respond to an action by the recipient. Promotional messages go through campaigns, which handle unsubscribes. A recipient who unsubscribed from your campaigns still receives your transactional emails.
Prerequisites
- A secret API key with the
send_transactional_emailpermission (andview_transactional_messagesto read sends). See Authentication. - Credits.
- A verified email sender (Settings › Senders). It is required: your emails always go out under your name.
Send
curl https://api.metaventus.com/v1/transactional/email \
-H "X-API-Key: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-20481" \
-d '{
"to": "marie@example.com",
"from": "contact@your-domain.com",
"subject": "Your order is confirmed",
"html": "<p>Hello Marie,</p><p>Your order 20481 is confirmed.</p>",
"reference": "order-20481"
}'
| Field | Required | Description |
|---|---|---|
to | yes | Recipient address. One per message. |
subject | yes | The subject, on one line, 998 characters at most. |
html | yes, or text | The HTML body, 1 MB at most. |
text | yes, or html | The text body. Without html, it is sent with its line breaks. |
from | no | A verified email sender of your account. Without from, your default sender. |
reply_to | no | The address that receives replies. |
reference | no | Your identifier (order number…), 128 characters at most. Returned as is, filterable. |
202 Accepted response: the message is accepted, billed and on its way.
{
"id": "922c2bfd-32ec-4773-b348-63967731e3a7",
"channel": "email",
"to": "marie@example.com",
"from": "contact@your-domain.com",
"subject": "Your order is confirmed",
"body": "<p>Hello Marie,</p><p>Your order 20481 is confirmed.</p>",
"status": "queued",
"reference": "order-20481",
"created_at": "2026-11-04T09:00:00Z",
"updated_at": "2026-11-04T09:00:00Z"
}
202 is not an error: it is the normal response to a send.
Never send twice
Pass an Idempotency-Key header unique to each message. If your request times out and
you replay it with the same key, the first message is returned with a 200 and the
Idempotent-Replayed: true header: nothing is resent, nothing is billed again.
Reusing a key for another message (different recipient, subject or content) is refused
(422 idempotency_key_reused).
Track delivery
Emails use the same routes as SMS: GET /v1/transactional/messages/{id} and
GET /v1/transactional/messages (see List messages).
status | Meaning |
|---|---|
queued | Accepted and billed, being sent. |
sent | Taken over by the sending service (sent_at). |
delivered | Accepted by the recipient's mail server (delivered_at). |
failed | Not delivered — see error_code. |
To be notified without polling the API, subscribe an endpoint to these events: see Receive your message events.
delivered means the recipient's server accepted the email, not that it was read or that
it reached the inbox rather than spam.
error_code | Cause | Billed |
|---|---|---|
rejected | Refused by the sending service (address or content). | No, refunded |
not_sent | Never handed over. | No, refunded |
bounced | Address refused by the recipient's server. | Yes |
Refusals
A refused send is neither sent nor billed. The body carries a stable code and an
explanation in error.
| Status | code | Cause | What to do |
|---|---|---|---|
400 | invalid_to, invalid_reply_to, invalid_subject, invalid_body, invalid_reference | Invalid request | Fix it |
402 | insufficient_credits | Insufficient balance (details.credits_needed, details.wallet_balance) | Top up, then retry |
403 | account_suspended | Subscription suspended | Settle it |
413 | body_too_long | Body over 1 MB | Shorten the message |
422 | sender_not_allowed | from is not a verified email sender of the account | Fix from |
422 | sender_required | No from and no verified default sender | Pass from, or set a default sender |
422 | idempotency_key_reused | Key already used for another message | New key |
429 | daily_limit_reached | Email limit of your plan reached for the period (details.limit, details.used) | Wait, or change plan |
503 | temporarily_unavailable | Temporary incident | Retry with the same Idempotency-Key |
The limit is shared with your campaigns, scenarios and appointment reminders: it is a single email allowance, whatever the sending channel.