Skip to main content

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 example order-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": "..." }, name is 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 html and text. See the "Sending with a Template" section;
  • variables — values for placeholders like {{name}}. They're substituted into the template, html, text, subject, and previewText;
  • 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 from domain 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, and bcc together. 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 429 with a Retry-After header — the number of seconds to wait.
  • {{unsubscribe_url}} — the unsubscribe link; EmailMassivo substitutes it and adds the List-Unsubscribe headers 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 suppressed or bounced and a reason — the email isn't sent to them;
  • the X-Quota-Remaining response header — the remaining email quota.

Possible Responses​

StatusDescription
202Email accepted for sending
400Bad Request — incorrect request format; the fields are listed in error.details
401Unauthorized — invalid or missing token
402Payment Required — the quota isn't enough for all recipients of the email
403Forbidden — the token lacks the email.send permission, or API access is disabled
404Not Found — the sending key, the sender domain, or the template wasn't found
409Conflict — the sender domain is blocked; or a request with this Idempotency-Key is still running, or the key was used with a different body
422Unprocessable 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
429Too Many Requests — request limit exceeded
500, 503Server 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.

Developer Documentation​