Skip to main content

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_email permission (and view_transactional_messages to 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"
}'
FieldRequiredDescription
toyesRecipient address. One per message.
subjectyesThe subject, on one line, 998 characters at most.
htmlyes, or textThe HTML body, 1 MB at most.
textyes, or htmlThe text body. Without html, it is sent with its line breaks.
fromnoA verified email sender of your account. Without from, your default sender.
reply_tonoThe address that receives replies.
referencenoYour 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).

statusMeaning
queuedAccepted and billed, being sent.
sentTaken over by the sending service (sent_at).
deliveredAccepted by the recipient's mail server (delivered_at).
failedNot 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_codeCauseBilled
rejectedRefused by the sending service (address or content).No, refunded
not_sentNever handed over.No, refunded
bouncedAddress 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.

StatuscodeCauseWhat to do
400invalid_to, invalid_reply_to, invalid_subject, invalid_body, invalid_referenceInvalid requestFix it
402insufficient_creditsInsufficient balance (details.credits_needed, details.wallet_balance)Top up, then retry
403account_suspendedSubscription suspendedSettle it
413body_too_longBody over 1 MBShorten the message
422sender_not_allowedfrom is not a verified email sender of the accountFix from
422sender_requiredNo from and no verified default senderPass from, or set a default sender
422idempotency_key_reusedKey already used for another messageNew key
429daily_limit_reachedEmail limit of your plan reached for the period (details.limit, details.used)Wait, or change plan
503temporarily_unavailableTemporary incidentRetry 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.