The EmailMassivo Email API lets you send transactional emails, such as order confirmations, password recovery emails, and notifications, with one POST request. Sending is performed through the public EmailMassivo API: you authenticate with an API key and specify which sending key should be used for the email.

Step 1. Create an API key

An API key gives access to the public EmailMassivo API with configurable permissions, also called scopes.

  1. In your account, open Integrations -> API and create an API key.
  2. Enter a name and enable the external_mail.send permission for sending transactional emails.
  3. Copy the token, for example rs_ck_v1_.... It is shown only once.

Step 2. Create a sending key

A sending key is the sending entity that connects a verified domain with sender reputation. Every email is sent through a specific sending key, and its numeric ID (key_id) is included directly in the request URL.

  1. In your account, open Transactional emails and create a key.
  2. Enter a name and select a verified domain.
  3. Copy the key ID from the key card, or get the list of keys with GET /api/v1/public/external-mails/keys. This request requires the external_mail.read permission.

Step 3. Send an email

POST https://api.emailmassivo.com/api/v1/external-mails/send/{key_id}

Pass the API key token in the Authorization header:

Authorization: Bearer rs_ck_v1_...

Request body example

{
  "idempotencyKey": "order-12345-confirmation",
  "mail": {
    "to": { "email": "user@example.com", "name": "John" },
    "from": { "email": "noreply@yourdomain.com", "name": "MyApp" },
    "subject": "Order confirmation",
    "html": "<h1>Thank you for your order!</h1>"
  }
}

Request fields

Field Type Required Description
mail.to.email string yes Recipient email address
mail.to.name string no Recipient name
mail.from.email string yes Sender address on the sending key domain
mail.from.name string no Sender name
mail.subject string <= 255 yes Email subject
mail.html / mail.text string at least one Email content
mail.previewTitle string <= 255 no Preheader text
mail.cc, mail.bcc string <= 255 no CC and BCC recipients, separated by commas
mail.headers object no Custom X-* headers
mail.attachments array <= 20 no Attachments in the { "filename": "base64" } format
idempotencyKey string <= 150 no, recommended Idempotency key

Send by template

To send an email using a template created in EmailMassivo, use this endpoint:

POST https://api.emailmassivo.com/api/v1/external-mails/send-by-template/{key_id}

Instead of html or text, pass idTemplateMailUser and params inside mail.

{
  "idempotencyKey": "order-12345-confirmation",
  "mail": {
    "to": { "email": "user@example.com", "name": "John" },
    "from": { "email": "noreply@yourdomain.com", "name": "MyApp" },
    "subject": "Order confirmation",
    "idTemplateMailUser": 123,
    "params": {
      "orderNumber": "12345",
      "customerName": "John"
    }
  }
}

idTemplateMailUser is the ID of the email template. params is an object with values for the template variables. The object keys must match the variables used in the template.

Idempotency

Pass your own idempotencyKey in every request. This ensures that if the same request is retried after a timeout or network error, the email is not sent twice.

If idempotencyKey is not provided, the server applies automatic duplicate protection, but it does not guarantee that there will be no missed or extra sends. In this case, the response can include warning.

Server responses

A successful response is 200 OK:

{ "uuid": "018e1234-abcd-7000-8000-000000000001" }

Use the uuid to track the email status.

Code When it occurs
400 Invalid request body or attachment issue: forbidden type or exceeded size
401 Invalid or revoked API key token
402 Not enough funds or the email limit for the plan is exhausted
403 The API key does not have external_mail.send, or the sending key is unavailable or inactive
404 Sending key or sender domain not found; for template sending, the template was not found
422 The recipient unsubscribed, complained, or the address is unavailable
429 Rate limit exceeded; retry after the time in Retry-After
503 The service is temporarily unavailable; retry later

The error body contains a machine-readable code and description.

Code examples

cURL

curl -X POST "https://api.emailmassivo.com/api/v1/external-mails/send/42" \
  -H "Authorization: Bearer $EMAILMASSIVO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "order-12345-confirmation",
    "mail": {
      "to": { "email": "user@example.com", "name": "John" },
      "from": { "email": "noreply@yourdomain.com", "name": "MyApp" },
      "subject": "Order confirmation",
      "html": "<h1>Thank you for your order!</h1>"
    }
  }'

PHP

$keyId = 42;
$payload = [
    'idempotencyKey' => 'order-12345-confirmation',
    'mail' => [
        'to' => ['email' => 'user@example.com', 'name' => 'John'],
        'from' => ['email' => 'noreply@yourdomain.com', 'name' => 'MyApp'],
        'subject' => 'Order confirmation',
        'html' => '<h1>Thank you for your order!</h1>',
    ],
];

$ch = curl_init("https://api.emailmassivo.com/api/v1/external-mails/send/{$keyId}");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('EMAILMASSIVO_API_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
echo $response;

Python

import os
import requests

key_id = 42
response = requests.post(
    f"https://api.emailmassivo.com/api/v1/external-mails/send/{key_id}",
    headers={"Authorization": f"Bearer {os.environ['EMAILMASSIVO_API_TOKEN']}"},
    json={
        "idempotencyKey": "order-12345-confirmation",
        "mail": {
            "to": {"email": "user@example.com", "name": "John"},
            "from": {"email": "noreply@yourdomain.com", "name": "MyApp"},
            "subject": "Order confirmation",
            "html": "<h1>Thank you for your order!</h1>",
        },
    },
)
print(response.json())

Node.js

const keyId = 42;

const response = await fetch(`https://api.emailmassivo.com/api/v1/external-mails/send/${keyId}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILMASSIVO_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    idempotencyKey: 'order-12345-confirmation',
    mail: {
      to: { email: 'user@example.com', name: 'John' },
      from: { email: 'noreply@yourdomain.com', name: 'MyApp' },
      subject: 'Order confirmation',
      html: '<h1>Thank you for your order!</h1>',
    },
  }),
});

console.log(await response.json());

JavaScript in the browser

Do not use an API key in browser code: the token will be visible to page visitors. Send emails only from the server. The Node.js example above can be used without changes in server-side JavaScript environments.

Limits

  • Request body: up to 5 MB.
  • Attachments: up to 15 MB total, no more than 20 files.
  • Executable files, archives, and system files are not allowed as attachments.
  • Public API rate limit: 300 requests per minute per API key. Check the X-RateLimit-* headers in the response.
  • Request encoding: UTF-8.