Creating an API Key

API key creation is available at: https://app.emailmassivo.com/api.

You can read detailed information about creating an API key in our Knowledge Base

Email Sending Route (with Ready HTML)

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

In the «X-Api-Key» header, you need to pass the API key as a string for authentication.

Request Body Example

{
   "idempotencyKey": "unique-key-string",
   "mail": {
        "to": {
            "email": "user@example.com",
            "name": "string"
        },
        "from": {
             "email": "user@example.com",
             "name": "string"
        },
        "subject": "string",
        "previewTitle": "string",
        "headers": {
        },
        "cc": "string",
        "bcc": "string",
        "html": "string",
        "text": "string"
   }
}

Field Descriptions

  • subject* (subject) — contains the email subject or title;
  • previewTitle — email preheader, up to 255 characters;
  • html*, text — if you pass both text and HTML versions simultaneously, the recipient's email client will decide which version to display to the user depending on their settings and capabilities. Usually, email clients display in HTML format if they support this function. Our service automatically generates text similar to html if text is not passed (or an empty string is passed);
  • name (to/from) — recipient/sender name;
  • headers — system email headers (optional field, for advanced users). https://nodemailer.com/message/custom-headers;
  • cc and bcc — this is the copy recipient address and blind copy recipient address;
    • cc (Carbon Copy) — this is the "copy" or "send copy" field. The recipient specified in CC will receive a copy of the message, but all recipients will be able to see who else copies of the message were sent to;
    • bcc (Blind Carbon Copy) — this is the "blind copy" field. This can be useful if you want to send a copy of the message to someone without revealing their address to other recipients.
      If recipients are specified in cc or bcc, the response will contain an additional field — additionalRecipients. It contains information about each such recipient.
  • attachments — email attachment (file), in the format of an array of files with the structure:

{ "filename.extension": "file body encoded in base64"};

  • idempotencyKey (String) — user idempotency key to prevent request duplication.
Sending Using Idempotency Key

If within one hour a repeated request to send an email with completely matching parameters arrives:

  • From (sender);
  • To (recipient);
  • Body (email body);
  • Subject (title);
  • Attachments (attachments).

Then:

  • without idempotency key API responds with code 200 and returns the same email uuid as in the first request, repeated sending does not create a new email;
  • with idempotency key (idempotencyKey, passed outside the mail block) emails are considered different when key values differ and will be sent again.
Usage Recommendations

We strongly recommend always passing your unique idempotencyKey.

Using a user idempotency key is considered necessary for reliable management of repeated requests.

The automatic repeat detection mechanism without a key exists only for backward compatibility and basic duplicate protection, but does not guarantee the absence of missed or extra sends.

Notes

  • The service limits request frequency: no more than 10 requests per second from one IP address are allowed.
  • Encoding cannot be specified, UTF-8 is always used;
  • The request accepts any system headers, but those set by us have priority, namely: Return-Path, List-Unsubscribe, Errors-To, X-Complaints-To, Precedence, Feedback-ID, X-SenderName-MailID, X-Mailru-Msgtype, X-Postmaster-Msgtype.

Possible Responses

Status Description
200 OK Email accepted for processing
400 Bad Request Request validation error
401 Unauthorized Invalid API key
402 Payment Required Not enough resources on the user balance
403 Forbidden API key is not active
404 Not Found Required resource was not found
422 Unprocessable Entity Recipient is unavailable
500 Internal Server Error Internal server error
503 Service Unavailable Email processing service is temporarily unavailable

200 OK

The email was accepted for processing.

Response fields:

Field Type Description
uuid string UUID of the sent email
additionalRecipients array Results for additional recipients from cc and bcc. Each item contains either uuid for a successfully accepted recipient or error for an invalid email address
warning string Returned if idempotencyKey was not provided

400 Bad Request

Possible messages:

Message Description
Attachments parse failed Attachments could not be parsed
Attachments size more than allowed Total attachment size exceeds the allowed limit
Attachments type forbidden Attachment file type is not allowed
HTML template is not valid HTML template is invalid for /send-by-template

404 Not Found

Possible messages:

Message Description
ExternalMailApiKey not found API key was not found
User Domain not found Sender domain was not found or is not linked to the user
TemplateMailUser not found by id Email template was not found for /send-by-template
MailUuid not found Email UUID was not found

422 Unprocessable Entity

Possible messages:

Message Description
Email receiver unsubscribed from this API key mails Recipient unsubscribed from emails sent with this API key
Email receiver complained from this API key mails Recipient complained about emails sent with this API key
Email receiver doesn't exist Recipient email does not exist
Email receiver unavailable Recipient email is temporarily unavailable
Template not found by templateId Template was not found for /send-by-template

Email Sending Route with Template

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

In the «X-Api-Key» header, you need to pass the API key as a string for authentication.

Request Body Example

{
   "idempotencyKey": "unique-key-string",
   "mail": {
        "to": {
            "email": "user@example.com",
            "name": "string"
        },
        "from": {
             "email": "user@example.com",
             "name": "string"
        },
        "subject": "string",
        "previewTitle": "string",
        "idTemplateMailUser": number,
        "params": {
            "test": "string",
            "test1": "string",
            "test2": "string"
        }
   }
}

Field Descriptions

  • idTemplateMailUser* — email template identifier created in EmailMassivo;
  • params — object with variables for substitution in the template. Object keys must match the variables used in the template.

Examples of Using API with EmailMassivo Email Template

PHP

$url = 'https://api.emailmassivo.com/api/v1/external-mails/send-by-template';
$data = array(
   'idempotencyKey' => 'unique-key-string',
   'mail' => array(
       'to' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'from' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'subject' => 'string',
       'previewTitle' => 'string',
       'idTemplateMailUser' => number,
       'params' => array(
           'test' => 'string',
           'test1' => 'string',
           'test2' => 'string'
       )
   )
);
$headers = array(
   'Content-Type' => 'application/json',
   'X-Api-Key' => 'YOUR_API_KEY'
);
$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
import json

url = 'https://api.emailmassivo.com/api/v1/external-mails/send-by-template'
data = {
    'idempotencyKey': 'unique-key-string',
    'mail': {
        'to': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'from': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'subject': 'string',
        'previewTitle': 'string',
        'idTemplateMailUser': number,
        'params': {
            'test': 'string',
            'test1': 'string',
            'test2': 'string'
        }
    }
}
headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
}
response = requests.post(url, json=data, headers=headers)

Node.js

const axios = require('axios');

const url = 'https://api.emailmassivo.com/api/v1/external-mails/send-by-template';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        idTemplateMailUser: number,
        params: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};

axios.post(url, data, { headers })
    .then(response => {
        // API response handling
    })
    .catch(error => {
        // Error handling
    });

JavaScript

const url = 'https://api.emailmassivo.com/api/v1/external-mails/send-by-template';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        idTemplateMailUser: number,
        params: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
    .then(response => response.json())
    .then(data => {
        // API response handling
    })
    .catch(error => {
        // Error handling
    });

If the request returns an error: "Invalid API key", replace the API key passing code with: 

$headers = array( 'Content-Type: application/json', 'X-Api-Key: YOUR_API_KEY');