Documentação Email API

Criação de API key

A criação de API key está disponível no link: https://app.emailmassivo.com/api.

Você pode ler informações detalhadas sobre a criação de API key em nossa Base de conhecimento.

Rota de envio de e-mail (com HTML pronto)

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

No cabeçalho «X-Api-Key» é necessário passar como string a chave API para autenticação.

Exemplo de corpo de solicitação

{
   "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"
   }
}

Descrição de campos

subject* (assunto) — contém o assunto ou título do e-mail;
previewTitle — preheader do e-mail, até 255 caracteres;
html*, text — se passarem tanto a versão de texto quanto a versão HTML simultaneamente, o cliente de e-mail do destinatário decidirá qual versão exibir ao usuário dependendo de suas configurações e capacidades. Geralmente, os clientes de e-mail exibem em formato HTML se suportam essa função. Nosso serviço gera automaticamente text similar a html se text não for passado (ou for passada uma string vazia);

name (to/from) — nome do destinatário/remetente do e-mail;
headers — cabeçalhos do sistema do e-mail (campo opcional, para usuários experientes). https://nodemailer.com/message/custom-headers;
cc e bcc — é o endereço do destinatário de cópia e o endereço do destinatário de cópia oculta;
- cc (Carbon Copy) — é o campo «cópia» ou «enviar cópia». O destinatário especificado em CC receberá uma cópia da mensagem, mas todos os destinatários poderão ver para quem mais foram enviadas cópias da mensagem;
- bcc (Blind Carbon Copy) — é o campo «cópia oculta». Isso pode ser útil se você deseja enviar uma cópia da mensagem para alguém sem revelar seu endereço a outros destinatários.
  Se destinatários forem especificados em cc ou bcc, na resposta estará presente um campo adicional — additionalRecipients. Ele contém informações sobre cada um desses destinatários.
attachments — anexo no e-mail (arquivo), em formato de matriz de arquivos com estrutura do tipo:

{ "nome_arquivo.extensão": "corpo do arquivo codificado em base64"};

idempotencyKey (String) — chave de idempotência do usuário para prevenir a duplicação de solicitações.

Envio usando chave de idempotência

Se dentro de uma hora chegar uma solicitação repetida para enviar um e-mail com parâmetros completamente coincidentes:

From (remetente);
To (destinatário);
Body (corpo do e-mail);
Subject (título);
Attachments (anexos).

Então:

sem chave de idempotência a API responde com o código 200 e retorna o mesmo uuid do e-mail que na primeira solicitação, o reenvio não cria um novo e-mail;
com chave de idempotência (idempotencyKey, é passada fora do bloco mail) os e-mails são considerados diferentes quando os valores da chave diferem e serão enviados novamente.

Recomendações de uso

Recomendamos enfaticamente passar sempre sua idempotencyKey única.

O uso da chave de idempotência do usuário é considerado necessário para um gerenciamento confiável de solicitações repetidas.

O mecanismo de detecção automática de repetições sem chave existe apenas para compatibilidade retroativa e proteção básica contra duplicação, mas não garante a ausência de envios omitidos ou adicionais.

Notas

O serviço limita a frequência de solicitações: são permitidas não mais de 10 solicitações por segundo de um endereço IP.
Não é possível especificar a codificação, sempre é usado UTF-8;
A solicitação aceita quaisquer cabeçalhos do sistema, mas os que estabelecemos têm prioridade, a saber: Return-Path, List-Unsubscribe, Errors-To, X-Complaints-To, Precedence, Feedback-ID, X-SenderName-MailID, X-Mailru-Msgtype, X-Postmaster-Msgtype.

Possíveis respostas

Status	Descrição
`200 OK`	O email foi aceito para processamento
`400 Bad Request`	Erro de validação da solicitação
`401 Unauthorized`	Chave API inválida
`402 Payment Required`	Não há recursos suficientes no saldo do usuário
`403 Forbidden`	A chave API não está ativa
`404 Not Found`	Um recurso necessário não foi encontrado
`422 Unprocessable Entity`	O destinatário não está disponível
`500 Internal Server Error`	Erro interno do servidor
`503 Service Unavailable`	O serviço de processamento de emails está temporariamente indisponível

200 OK

O email foi aceito para processamento.

Campos da resposta:

Campo	Tipo	Descrição
`uuid`	`string`	UUID do email enviado
`additionalRecipients`	`array`	Resultados para destinatários adicionais de `cc` e `bcc`. Cada item contém `uuid` para um destinatário aceito com sucesso ou `error` para um endereço de email inválido
`warning`	`string`	Retornado se `idempotencyKey` não foi enviado

400 Bad Request

Mensagens possíveis:

Mensagem	Descrição
`Attachments parse failed`	Não foi possível processar os anexos
`Attachments size more than allowed`	O tamanho total dos anexos excede o limite permitido
`Attachments type forbidden`	O tipo de arquivo anexado não é permitido
`HTML template is not valid`	O template HTML não é válido para `/send-by-template`

404 Not Found

Mensagens possíveis:

Mensagem	Descrição
`ExternalMailApiKey not found`	A chave API não foi encontrada
`User Domain not found`	O domínio do remetente não foi encontrado ou não está vinculado ao usuário
`TemplateMailUser not found by id`	O template de email não foi encontrado para `/send-by-template`
`MailUuid not found`	O UUID do email não foi encontrado

422 Unprocessable Entity

Mensagens possíveis:

Mensagem	Descrição
`Email receiver unsubscribed from this API key mails`	O destinatário cancelou a inscrição dos emails enviados com esta chave API
`Email receiver complained from this API key mails`	O destinatário reclamou dos emails enviados com esta chave API
`Email receiver doesn't exist`	O email do destinatário não existe
`Email receiver unavailable`	O email do destinatário está temporariamente indisponível
`Template not found by templateId`	O template não foi encontrado para `/send-by-template`

Rota de envio de e-mail com template

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

No cabeçalho «X-Api-Key» é necessário passar como string a chave API para autenticação.

Exemplo de corpo de solicitação

{
   "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"
        }
   }
}

Descrição de campos

idTemplateMailUser* — identificador do template de e-mail criado no EmailMassivo;
params — objeto com variáveis para substituir no template. As chaves do objeto devem corresponder às variáveis utilizadas no template.

Exemplos de uso de API com template de e-mail EmailMassivo

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 => {
        // Processamento de resposta API
    })
    .catch(error => {
        // Processamento de erro
    });

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 => {
        // Processamento de resposta API
    })
    .catch(error => {
        // Processamento de erro
    });

Se a solicitação retornar um erro: «Chave API incorreta», substitua o código de transmissão de API key por:
$headers = array( 'Content-Type: application/json', 'X-Api-Key: YOUR_API_KEY');