Sending a transactional e-mail through the API: the fields of POST /v1/email/messages

The short answer: an e-mail is a POST /v1/email/messages request with a sender on a verified domain, the recipients, the subject and the content in html, text or both (or a template_id). Without send_at, the e-mail goes out straight away and the answer, with code 201, has its real status.

The request fields

Field	What it takes
from	The sender, on a verified domain or a subdomain of it: invoices@yourcompany.com or Your Company <invoices@yourcompany.com>
from_name	Optional: the name shown next to the address
to, cc, bcc	One address, a comma-separated list or an array. At most 50 recipients per e-mail, counting all three
reply_to	Up to 5 addresses where replies go
subject	The subject, up to 998 characters. It can have variables
html / text	The content. Send both whenever you can
template_id and variables	A saved template and the values for its variables. See templates with variables
attachments	Files in base64. See attaching invoices and tickets
send_at	Optional: the date and time to send. See scheduling an e-mail

An example

curl https://api.mozout.com/v1/email/messages \
-H "Authorization: Bearer sandbox_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fatura-2026-214" \
-d '{"from": "Your Company <invoices@yourcompany.com>",
"to": ["ana@example.com"],
"reply_to": "accounts@yourcompany.com",
"subject": "Invoice FT 2026/214 is ready",
"html": "<p>Hello Ana, your invoice is now available.</p>",
"text": "Hello Ana, your invoice is now available."}'

What the answer contains

Field	What it says
id	The e-mail number, to look it up later with GET /v1/email/messages/{id}
status	The status: sent once it has left, simulated in Sandbox. See e-mail statuses
recipients and credits	How many recipients counted and how many credits it used
charged	Whether the send has been charged
suppressed	Recipients that were on the suppression list and were left out, at no cost

Retrying without sending twice

Send the Idempotency-Key header with one unique value per e-mail, such as invoice-2026-214. If the connection drops and you repeat the request with the same value and body, you get the stored answer and the e-mail does not go out again. The same value with a different body gives 409 with idempotency_conflict. The general idea is in timeouts, retries and idempotency.

Never call the API from the customer's browser. The key would be visible to anyone who opened the page. The request always goes from your server.

Working in PHP? The request is a POST with JSON, as in calling a web API from PHP with cURL.

Want to see everything the API does and create your key? See the API page.

See the API page

Categories

Categories