Pular para o conteúdo principal

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.

Para enviar e-mails, a API key precisa da permissão «Envio de e-mails pela Email API» (email.send) do grupo «Correio». Você pode ler informações detalhadas sobre a criação de API key em nossa Base de conhecimento.

Você também precisa de um domínio verificado e de uma chave de envio desse domínio. Não é obrigatório informar a chave de envio na solicitação: sem keyId, o e-mail é enviado pela chave padrão do domínio do remetente.

Importante: os e-mails de teste devem ser enviados apenas para endereços de e-mail existentes, caso contrário a chave será bloqueada.

Rota de envio de e-mail​

POST https://api.emailmassivo.com/api/v1/public/emails

A mesma rota envia tanto e-mails com HTML ou texto prontos quanto e-mails com template.

Cabeçalhos da solicitação:

  • Authorization: Bearer SEU_TOKEN — o token da API key;
  • Content-Type: application/json;
  • Idempotency-Key — um rótulo único do e-mail no seu sistema, por exemplo order-12345-confirmation. Não é obrigatório, mas recomendamos enviá-lo sempre: veja a seção «Idempotência» abaixo.

Exemplo de corpo de solicitação​

{
  "data": {
    "from": { "email": "noreply@seu-dominio.com", "name": "Minha loja" },
    "to": { "email": "cliente@example.com", "name": "João" },
    "cc": [{ "email": "gerente@seu-dominio.com" }],
    "bcc": [{ "email": "arquivo@seu-dominio.com" }],
    "replyTo": { "email": "suporte@seu-dominio.com" },
    "subject": "Seu pedido {{order}} foi confirmado",
    "previewText": "Obrigado pelo seu pedido",
    "html": "<h1>Obrigado, {{name}}!</h1>",
    "text": "Obrigado, {{name}}!",
    "variables": { "name": "João", "order": "#12345" },
    "headers": { "X-Order-Id": "12345" },
    "attachments": [
      { "fileName": "fatura.pdf", "content": "JVBERi0xLjQK..." }
    ],
    "keyId": 42
  }
}

Descrição de campos​

Todos os campos ficam dentro do objeto data.

  • from* — o remetente: { "email": "...", "name": "..." }, name é opcional. O endereço deve pertencer ao domínio da chave de envio, e o domínio deve estar verificado;
  • to* — os destinatários principais: um objeto { email, name } ou uma matriz desses objetos;
  • cc e bcc — cópia e cópia oculta, matrizes de objetos { email, name };
    • cc (Carbon Copy) — o destinatário recebe uma cópia do e-mail, e todos os destinatários podem ver para quem mais ele foi enviado;
    • bcc (Blind Carbon Copy) — o destinatário recebe uma cópia, e seu endereço não é exibido aos demais destinatários;
  • replyTo — o endereço para respostas: um objeto ou uma matriz de até 5 endereços;
  • subject* — o assunto do e-mail, até 255 caracteres;
  • previewText — o preheader do e-mail, até 255 caracteres;
  • html, text — as versões HTML e de texto do e-mail. Se você enviar as duas, o cliente de e-mail do destinatário decide qual versão exibir;
  • templateId ou templateAlias — um template criado no EmailMassivo, pelo identificador ou pelo alias, no lugar de html e text. Veja a seção «Envio com template»;
  • variables — valores para os marcadores do tipo {{name}}. São substituídos no template, em html, text, subject e previewText;
  • headers — cabeçalhos próprios do e-mail (campo opcional, para usuários experientes). Cabeçalhos do sistema não podem ser enviados;
  • attachments — arquivos anexados ao e-mail: { "fileName": "fatura.pdf", "content": "<base64>" };
  • keyId — o identificador da chave de envio. Se não for informado, é usada a chave padrão do domínio de from.

Importante: O e-mail precisa de conteúdo: html, text ou um template. Não é possível combinar um template com html ou text.

Idempotência​

Se for necessário repetir uma solicitação — por exemplo, após uma falha de rede ou um tempo limite esgotado —, envie-a novamente com o mesmo Idempotency-Key e exatamente o mesmo corpo:

  • com a mesma chave, a API retorna a resposta da primeira solicitação, e o e-mail não é enviado uma segunda vez. A chave é válida por 24 horas;
  • sem chave, cada solicitação cria um novo e-mail.

A chave tem de 1 a 64 caracteres: letras latinas, dígitos e ., _, :, -. Vincule-a a um evento do seu sistema: um valor aleatório a cada tentativa não protege contra duplicidades.

Notas​

  • Até 50 destinatários em to, cc e bcc no total. O mesmo endereço não pode aparecer duas vezes entre eles.
  • Até 20 anexos, 15 MB no total.
  • A rota aceita até 600 solicitações por minuto por API key.
  • Até 20 e-mails por segundo a partir de um mesmo domínio remetente. Acima de qualquer um dos limites, a API responde 429 com o cabeçalho Retry-After: os segundos que é preciso esperar.
  • {{unsubscribe_url}} — o link de descadastro; o EmailMassivo o substitui e adiciona por conta própria os cabeçalhos List-Unsubscribe.

Resposta​

Se o e-mail for aceito, a API responde com o código 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": "cliente@example.com",
        "name": "João",
        "type": "to",
        "status": "queued",
        "reason": null
      }
    ]
  },
  "meta": { "requestId": "01JB2W...", "timestamp": "2026-09-30T10:15:00.120Z" }
}
  • data.id — o identificador do e-mail. Com ele você consulta o status de entrega; os webhooks o enviam como emailId;
  • data.recipients — todos os destinatários do e-mail, cada um com seu próprio identificador e status. Um destinatário que se descadastrou ou cujo endereço é conhecido como não entregável aparece com o status suppressed ou bounced e um motivo: o e-mail não é enviado a ele;
  • o cabeçalho de resposta X-Quota-Remaining — a cota de e-mails restante.

Possíveis respostas​

StatusDescrição
202E-mail aceito para envio
400Bad Request — formato de solicitação incorreto; os campos estão listados em error.details
401Unauthorized — token incorreto ou ausente
402Payment Required — a cota não é suficiente para todos os destinatários do e-mail
403Forbidden — o token não tem a permissão email.send, ou o acesso à API está desativado
404Not Found — a chave de envio, o domínio do remetente ou o template não foi encontrado
409Conflict — o domínio remetente está bloqueado; ou uma solicitação com este Idempotency-Key ainda está em processamento, ou a chave foi usada com outro corpo
422Unprocessable Entity — por exemplo, a chave de envio não está ativa, from não pertence ao domínio da chave ou nenhum dos destinatários de to pode receber o e-mail
429Too Many Requests — limite de solicitações excedido
500, 503Erro do servidor — repita a solicitação com o mesmo Idempotency-Key

Os erros chegam no formato { "ok": false, "error": { "code", "message", "details" }, "meta" }. Todos os códigos estão na referência de códigos de erro (em inglês).

Envio com template​

E-mails com template são enviados pela mesma rota. No lugar de html e text, informe templateId — o identificador do template — ou templateAlias — o alias dele, por exemplo order-confirmation.

Exemplo de corpo de solicitação​

{
  "data": {
    "from": { "email": "noreply@seu-dominio.com", "name": "Minha loja" },
    "to": { "email": "cliente@example.com", "name": "João" },
    "subject": "Seu pedido foi confirmado",
    "previewText": "Obrigado pelo seu pedido",
    "templateId": 123,
    "variables": {
      "test": "string",
      "test1": "string",
      "test2": "string"
    }
  }
}

Descrição de campos​

  • templateId* ou templateAlias* — o identificador ou o alias do template de e-mail criado no EmailMassivo. Informe apenas um deles;
  • variables — 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/public/emails';
$data = array(
   'data' => array(
       'from' => array(
           'email' => 'noreply@seu-dominio.com',
           'name' => 'Minha loja'
       ),
       'to' => array(
           'email' => 'cliente@example.com',
           'name' => 'João'
       ),
       'subject' => 'Seu pedido foi confirmado',
       'templateId' => 123,
       'variables' => array(
           'test' => 'string',
           'test1' => 'string',
           'test2' => 'string'
       )
   )
);
$headers = array(
   'Content-Type: application/json',
   'Authorization: Bearer SEU_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@seu-dominio.com',
            'name': 'Minha loja'
        },
        'to': {
            'email': 'cliente@example.com',
            'name': 'João'
        },
        'subject': 'Seu pedido foi confirmado',
        'templateId': 123,
        'variables': {
            'test': 'string',
            'test1': 'string',
            'test2': 'string'
        }
    }
}
headers = {
    'Authorization': 'Bearer SEU_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@seu-dominio.com',
            name: 'Minha loja'
        },
        to: {
            email: 'cliente@example.com',
            name: 'João'
        },
        subject: 'Seu pedido foi confirmado',
        templateId: 123,
        variables: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer SEU_TOKEN',
    'Idempotency-Key': 'order-12345-confirmation'
};

axios.post(url, data, { headers })
    .then(response => {
        // Processamento de resposta API: response.data.data.id
    })
    .catch(error => {
        // Processamento de erro: error.response.data.error.code
    });

JavaScript (navegador)​

Não use a API key no código do navegador: o token ficaria visível para qualquer visitante da página. Envie e-mails apenas a partir do seu servidor; o exemplo de Node.js também serve para outros ambientes JavaScript de servidor.

Migração para a Email API​

Se a sua integração usa os métodos de envio anteriores, eles continuam funcionando. Como passar para a nova rota está descrito no guia Migrating to the Email API (em inglês).

Documentação para desenvolvedores​

A documentação para desenvolvedores está disponível em inglês: