Send transactional email
Send receipts, password resets and alerts with one API call. Idempotency keys, delivery status and test sends explained.
Transactional emails go to one person because of something they did: a receipt, a password reset, a sign-in link, an alert. Send each one with a single request to POST /api/v1/emails.
Send an email#
Send [email protected] a receipt for order #1042 from [email protected]: 2 seats of Pro, $58 total.
Email [email protected] from [email protected] using my welcome template, with her first name.
Did the email to [email protected] get delivered? Did she open it?
from must use a verified domain. Add text for a plain-text version; if you only send html, that's fine too.
Send with a template#
Save the design once as a template, then send it by alias with the values for its variables:
{
"from": "Acme <[email protected]>",
"to": "[email protected]",
"template": "welcome",
"variables": { "first_name": "Ada", "plan": "Pro" }
}Retries and idempotency#
Network errors happen. Send an Idempotency-Key header with a value that's unique for that email (an order id, for example). If you retry with the same key, Maillayer returns the original email instead of sending a second one.
Idempotency-Key: receipt-order-1042
Delivery status#
The response includes the email's id and status. Fetch GET /api/v1/emails/:id later to see what happened:
| Status | Meaning |
|---|---|
queued | Accepted, about to go out. |
sent | Handed to the receiving mail server. |
delivered | The receiving server accepted it. |
deferred | Temporarily delayed by the receiver; we keep retrying. |
bounced | Rejected for good. The address is suppressed. |
complained | The recipient marked it as spam. The address is suppressed. |
dropped | Not sent because the address is suppressed. |
failed | Couldn't be sent. The credit is returned. |
Credits#
- Each email uses one credit. Failed and dropped emails give the credit back.
- Before your first purchase, three test emails to your own account address are free. After that, sending needs credits; see Credits and billing.
Full request and response fields: Emails API.