A Email API da EmailMassivo permite enviar e-mails transacionais, como confirmações de pedido, recuperação de senha e notificações, com uma única solicitação POST. O envio é feito pela API pública da EmailMassivo: você se autentica com uma API key e informa qual sending key deve ser usada para o e-mail.

Etapa 1. Crie uma API key

Uma API key dá acesso à API pública da EmailMassivo com permissões configuráveis, também chamadas de scopes.

  1. Na sua conta, abra Integrations -> API e crie uma API key.
  2. Informe um nome e ative a permissão external_mail.send para enviar e-mails transacionais.
  3. Copie o token, por exemplo rs_ck_v1_.... Ele é exibido apenas uma vez.

Etapa 2. Crie uma sending key

Uma sending key é a entidade de envio que conecta um domínio verificado à reputação do remetente. Todo e-mail é enviado por uma sending key específica, e o ID numérico dela (key_id) é incluído diretamente na URL da solicitação.

  1. Na sua conta, abra Transactional emails e crie uma key.
  2. Informe um nome e selecione um domínio verificado.
  3. Copie o ID da key no card dela, ou obtenha a lista de keys com GET /api/v1/public/external-mails/keys. Essa solicitação requer a permissão external_mail.read.

Etapa 3. Envie um e-mail

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

Passe o token da API key no cabeçalho Authorization:

Authorization: Bearer rs_ck_v1_...

Exemplo de corpo da solicitação

{
  "idempotencyKey": "order-12345-confirmation",
  "mail": {
    "to": { "email": "user@example.com", "name": "Joao" },
    "from": { "email": "noreply@yourdomain.com", "name": "MyApp" },
    "subject": "Confirmacao do pedido",
    "html": "<h1>Obrigado pelo seu pedido!</h1>"
  }
}

Campos da solicitação

Campo Tipo Obrigatório Descrição
mail.to.email string sim Endereço do destinatário
mail.to.name string não Nome do destinatário
mail.from.email string sim Endereço do remetente no domínio da sending key
mail.from.name string não Nome do remetente
mail.subject string <= 255 sim Assunto do e-mail
mail.html / mail.text string pelo menos um Conteúdo do e-mail
mail.previewTitle string <= 255 não Texto de preheader
mail.cc, mail.bcc string <= 255 não Destinatários CC e BCC, separados por vírgulas
mail.headers object não Cabeçalhos personalizados X-*
mail.attachments array <= 20 não Anexos no formato { "filename": "base64" }
idempotencyKey string <= 150 não, recomendado Chave de idempotência

Envio por template

Para enviar um e-mail usando um template criado na EmailMassivo, use este endpoint:

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

Em vez de html ou text, passe idTemplateMailUser e params dentro de mail.

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

idTemplateMailUser é o ID do template de e-mail. params é um objeto com valores para as variáveis do template. As chaves do objeto devem corresponder às variáveis usadas no template.

Idempotência

Passe seu próprio idempotencyKey em cada solicitação. Isso garante que, se a mesma solicitação for repetida após um timeout ou erro de rede, o e-mail não seja enviado duas vezes.

Se idempotencyKey não for enviado, o servidor aplica uma proteção automática contra duplicados, mas ela não garante que não haverá envios omitidos ou extras. Nesse caso, a resposta pode incluir warning.

Respostas do servidor

Uma resposta bem-sucedida é 200 OK:

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

Use o uuid para acompanhar o status do e-mail.

Código Quando ocorre
400 Corpo da solicitação inválido ou problema com anexos: tipo proibido ou tamanho excedido
401 Token de API key inválido ou revogado
402 Saldo insuficiente ou limite de e-mails do plano esgotado
403 A API key não tem external_mail.send, ou a sending key está indisponível ou inativa
404 Sending key ou domínio do remetente não encontrado; no envio por template, o template não foi encontrado
422 O destinatário cancelou a inscrição, reclamou ou o endereço está indisponível
429 Limite de solicitações excedido; tente novamente após o tempo em Retry-After
503 O serviço está temporariamente indisponível; tente novamente mais tarde

O corpo do erro contém um código legível por máquina e uma descrição.

Exemplos de código

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": "Joao" },
      "from": { "email": "noreply@yourdomain.com", "name": "MyApp" },
      "subject": "Confirmacao do pedido",
      "html": "<h1>Obrigado pelo seu pedido!</h1>"
    }
  }'

PHP

$keyId = 42;
$payload = [
    'idempotencyKey' => 'order-12345-confirmation',
    'mail' => [
        'to' => ['email' => 'user@example.com', 'name' => 'Joao'],
        'from' => ['email' => 'noreply@yourdomain.com', 'name' => 'MyApp'],
        'subject' => 'Confirmacao do pedido',
        'html' => '<h1>Obrigado pelo seu pedido!</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": "Joao"},
            "from": {"email": "noreply@yourdomain.com", "name": "MyApp"},
            "subject": "Confirmacao do pedido",
            "html": "<h1>Obrigado pelo seu pedido!</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: 'Joao' },
      from: { email: 'noreply@yourdomain.com', name: 'MyApp' },
      subject: 'Confirmacao do pedido',
      html: '<h1>Obrigado pelo seu pedido!</h1>',
    },
  }),
});

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

JavaScript no navegador

Não use uma API key em código de navegador: o token ficará visível para os visitantes da página. Envie e-mails apenas pelo servidor. O exemplo de Node.js acima pode ser usado sem alterações em ambientes JavaScript do lado do servidor.

Limites

  • Corpo da solicitação: até 5 MB.
  • Anexos: até 15 MB no total, no máximo 20 arquivos.
  • Arquivos executáveis, compactados e de sistema não são permitidos como anexos.
  • Limite da API pública: 300 solicitações por minuto por API key. Verifique os cabeçalhos X-RateLimit-* na resposta.
  • Codificação da solicitação: UTF-8.