Email API Documentation
Creating an API Key
API key creation is available at: https://app.emailmassivo.com/api.
To send emails, the API key needs the "Sending emails via the Email API" permission (email.send) in the "Mail" group. You can read detailed information about creating an API key in our Knowledge Base.
You also need a verified domain and a sending key on that domain. You don't have to pass the sending key in the request: without keyId, the email goes through the default key of the sender's domain.
Important: test emails must be sent only to existing email addresses, otherwise the key will be banned.
Email Sending Route
POST https://api.emailmassivo.com/api/v1/public/emails
The same route sends an email with ready-made HTML or text and an email from a template.
Request headers:
Authorization: Bearer YOUR_TOKEN— the API key token;Content-Type: application/json;Idempotency-Key— a unique label of the email in your system, for exampleorder-12345-confirmation. Optional, but we strongly recommend always passing it: see the "Idempotency" section below.
Request Body Example
{
"data": {
"from": { "email": "noreply@your-domain.com", "name": "My Shop" },
"to": { "email": "client@example.com", "name": "John" },
"cc": [{ "email": "manager@your-domain.com" }],
"bcc": [{ "email": "archive@your-domain.com" }],
"replyTo": { "email": "support@your-domain.com" },
"subject": "Your order {{order}} is confirmed",
"previewText": "Thank you for your order",
"html": "<h1>Thank you, {{name}}!</h1>",
"text": "Thank you, {{name}}!",
"variables": { "name": "John", "order": "#12345" },
"headers": { "X-Order-Id": "12345" },
"attachments": [
{ "fileName": "invoice.pdf", "content": "JVBERi0xLjQK..." }
],
"keyId": 42
}
}
Field Description
All fields go inside the data object.
- from* — the sender:
{ "email": "...", "name": "..." },nameis optional. The address must be on the sending key's domain, and the domain must be verified; - to* — the primary recipients: one
{ email, name }object or an array of them; - cc and bcc — copy and blind copy, arrays of
{ email, name }objects;- cc (Carbon Copy) — the recipient gets a copy of the email, and all recipients can see who else received it;
- bcc (Blind Carbon Copy) — the recipient gets a copy, and their address isn't shown to the other recipients;
- replyTo — the address for replies: an object or an array of up to 5 addresses;
- subject* — the subject of the email, up to 255 characters;
- previewText — the email preheader, up to 255 characters;
- html, text — the HTML and text versions of the email. If you pass both, the recipient's mail client decides which version to show;
- templateId or templateAlias — a template created in EmailMassivo, by its id or by its alias, instead of
htmlandtext. See the "Sending with a Template" section; - variables — values for placeholders like
{{name}}. They're substituted into the template,html,text,subject, andpreviewText; - headers — your own email headers (optional field, for experienced users). System headers can't be passed;
- attachments — files attached to the email:
{ "fileName": "invoice.pdf", "content": "<base64>" }; - keyId — the sending key id. If it isn't passed, the default key of the
fromdomain is used.
Important:
An email needs content: html, text, or a template. You can't combine a template with html or text.
Idempotency
If a request has to be repeated — for example, after a network failure or a timeout — send it again with the same Idempotency-Key and exactly the same body:
- with the same key, the API returns the response to the first request, and the email isn't sent a second time. The key is valid for 24 hours;
- without a key, every request creates a new email.
The key is 1 to 64 characters: Latin letters, digits, and ., _, :, -. Tie it to an event in your system — a random value for every attempt doesn't protect against duplicates.
Notes
- Up to 50 recipients in
to,cc, andbcctogether. The same address can't appear twice among them. - Up to 20 attachments, 15 MB in total.
- The route accepts up to 600 requests per minute per API key.
- Up to 20 emails per second from one sender domain. Above either limit the API responds
429with aRetry-Afterheader — the number of seconds to wait. {{unsubscribe_url}}— the unsubscribe link; EmailMassivo substitutes it and adds theList-Unsubscribeheaders itself.
Response
If the email is accepted, the API responds with code 202:
{
"ok": true,
"data": {
"id": "0199b2f4-6c1e-7a3d-9f2b-4e8c1d7a5b60",
"status": "queued",
"createdAt": "2026-09-30T10:15:00.000Z",
"recipients": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c3d9e01",
"email": "client@example.com",
"name": "John",
"type": "to",
"status": "queued",
"reason": null
}
]
},
"meta": { "requestId": "01JB2W...", "timestamp": "2026-09-30T10:15:00.120Z" }
}
- data.id — the email identifier. Use it to check the delivery status; webhooks send it as
emailId; - data.recipients — all recipients of the email, each with its own identifier and status. A recipient who unsubscribed or whose address is known as undeliverable comes with the status
suppressedorbouncedand a reason — the email isn't sent to them; - the
X-Quota-Remainingresponse header — the remaining email quota.
Possible Responses
| Status | Description |
|---|---|
| 202 | Email accepted for sending |
| 400 | Bad Request — incorrect request format; the fields are listed in error.details |
| 401 | Unauthorized — invalid or missing token |
| 402 | Payment Required — the quota isn't enough for all recipients of the email |
| 403 | Forbidden — the token lacks the email.send permission, or API access is disabled |
| 404 | Not Found — the sending key, the sender domain, or the template wasn't found |
| 409 | Conflict — the sender domain is blocked; or a request with this Idempotency-Key is still running, or the key was used with a different body |
| 422 | Unprocessable Entity — for example, the sending key isn't active, from isn't on the key's domain, or none of the to recipients can receive the email |
| 429 | Too Many Requests — request limit exceeded |
| 500, 503 | Server error — retry with the same Idempotency-Key |
Errors come in the format { "ok": false, "error": { "code", "message", "details" }, "meta" }. All codes are in the error code reference.
Sending with a Template
Templates are sent through the same route. Instead of html and text, pass templateId — the template id — or templateAlias — its alias, for example order-confirmation.
Request Body Example
{
"data": {
"from": { "email": "noreply@your-domain.com", "name": "My Shop" },
"to": { "email": "client@example.com", "name": "John" },
"subject": "Your order is confirmed",
"previewText": "Thank you for your order",
"templateId": 123,
"variables": {
"test": "string",
"test1": "string",
"test2": "string"
}
}
}
Field Description
- templateId* or templateAlias* — the id or alias of an email template created in EmailMassivo. Pass only one of them;
- variables — an object with variables to substitute in the template. The object keys must match the variables used in the template.
API Usage Examples with an EmailMassivo Email Template
PHP
$url = 'https://api.emailmassivo.com/api/v1/public/emails';
$data = array(
'data' => array(
'from' => array(
'email' => 'noreply@your-domain.com',
'name' => 'My Shop'
),
'to' => array(
'email' => 'client@example.com',
'name' => 'John'
),
'subject' => 'Your order is confirmed',
'templateId' => 123,
'variables' => array(
'test' => 'string',
'test1' => 'string',
'test2' => 'string'
)
)
);
$headers = array(
'Content-Type: application/json',
'Authorization: Bearer YOUR_TOKEN',
'Idempotency-Key: order-12345-confirmation'
);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
Python
import requests
url = 'https://api.emailmassivo.com/api/v1/public/emails'
data = {
'data': {
'from': {
'email': 'noreply@your-domain.com',
'name': 'My Shop'
},
'to': {
'email': 'client@example.com',
'name': 'John'
},
'subject': 'Your order is confirmed',
'templateId': 123,
'variables': {
'test': 'string',
'test1': 'string',
'test2': 'string'
}
}
}
headers = {
'Authorization': 'Bearer YOUR_TOKEN',
'Idempotency-Key': 'order-12345-confirmation'
}
response = requests.post(url, json=data, headers=headers)
email_id = response.json()['data']['id']
Node.js
const axios = require('axios');
const url = 'https://api.emailmassivo.com/api/v1/public/emails';
const data = {
data: {
from: {
email: 'noreply@your-domain.com',
name: 'My Shop'
},
to: {
email: 'client@example.com',
name: 'John'
},
subject: 'Your order is confirmed',
templateId: 123,
variables: {
test: 'string',
test1: 'string',
test2: 'string'
}
}
};
const headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN',
'Idempotency-Key': 'order-12345-confirmation'
};
axios.post(url, data, { headers })
.then(response => {
// API response handling: response.data.data.id
})
.catch(error => {
// Error handling: error.response.data.error.code
});
JavaScript (browser)
Don't use the API key in browser code — the token would be visible to any visitor of the page. Send emails only from your server; the Node.js example above works in other server-side JavaScript environments too.
Migrating to the Email API
If your integration uses the earlier sending methods, they keep working. How to move to the new route is described in the guide Migrating to the Email API.