Enviar um e-mail

Este guia explica cada parte de uma requisição POST /emails e o que o Emailit faz com ela, do endereço From aos erros que você pode receber. Para a referência completa dos parâmetros, consulte Enviar um e-mail na referência da API.

Antes de começar

• Um domínio de envio verificado no seu workspace. Consulte Adicionar um domínio.
• Uma chave de API com escopo Full Access ou Sending Only. Consulte Chaves de API.
• Acesso de produção, se você enviar para alguém que não seja membro do workspace. Consulte Acesso de produção.
• Créditos suficientes para todos os destinatários (1 crédito cada).

Enviar um e-mail básico

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'

import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});

import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);

Definir o endereço From

from é obrigatório e aceita um endereço em qualquer uma destas formas:

• billing@acme.com
• Acme Billing <billing@acme.com> ou, com aspas, "Acme, Inc." <billing@acme.com>

O domínio depois do @ deve ser um domínio de envio verificado no mesmo workspace:

• A correspondência é exata. Os domínios são comparados sem diferenciar maiúsculas de minúsculas, mas mail.acme.com e acme.com são domínios diferentes. Adicione e verifique cada subdomínio de onde você envia.
• Qualquer parte local funciona. Você não precisa de uma caixa de e-mail para billing@ ou no-reply@.
• Domínios pendentes não podem enviar. Um domínio que ainda aguarda análise (Pending verification) é tratado como não verificado.
• Chaves restritas só usam o domínio delas. Uma chave Sending Only restrita a um domínio só pode enviar desse domínio.
• Domínios pausados são bloqueados. Se a saúde de envio pausou o domínio, os envios a partir dele são rejeitados até a pausa ser retirada.

Adicionar destinatários

to é obrigatório. cc e bcc são opcionais. Cada campo aceita uma string ou um array de strings, com ou sem nomes de exibição, e comporta até 50 endereços. Uma string pode conter vários endereços separados por vírgula; use um array quando o próprio nome de exibição tiver uma vírgula.

O Emailit remove os endereços duplicados entre to, cc e bcc (sem diferenciar maiúsculas de minúsculas) e depois cria um e-mail por destinatário único, cada um com o seu próprio ID em_. Todas as cópias levam os mesmos cabeçalhos To e Cc, então os destinatários veem a conversa normalmente, e os destinatários em Bcc nunca aparecem nos cabeçalhos de nenhuma cópia.

Quando uma requisição tem mais de um destinatário, a resposta inclui um mapa ids de destinatário para ID de e-mail. id é o e-mail do primeiro destinatário.

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}

Cada destinatário custa 1 crédito e conta para os seus limites de requisições. Um destinatário com uma supressão do tipo recipient é aceito e depois marcado como suppressed, em vez de ser entregue.

Escrever o conteúdo

Se reply_to tiver o mesmo endereço que from, o Emailit remove o cabeçalho Reply-To, porque ele não acrescenta nada e alguns filtros de spam o penalizam.

Enviar com um template

Defina template como o alias de um template ou um ID tem_ e passe em variables os valores para as variáveis do Temple que ele contém.

• Um alias envia a versão publicada no momento para esse alias. Se nenhuma versão estiver publicada, a requisição falha com 404.
• Um ID tem_ envia exatamente essa versão, publicada ou não. Use-o para testar uma versão em rascunho antes de publicá-la.

Os campos da requisição têm precedência sobre o template: um subject, html ou text que você enviar substitui o valor do template. Se você não enviar reply_to, o Reply-To do template é usado. from é sempre obrigatório na requisição. Consulte Versões de templates para saber como a publicação funciona.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})

$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);

variables também funciona sem template: o Emailit renderiza as variáveis do Temple no subject, no html e no text que você envia diretamente na requisição.

Controlar o rastreamento

Por padrão, cada e-mail segue as configurações Track loads e Track clicks do seu domínio de envio. Para substituí-las em um e-mail, use tracking:

• "tracking": true ou false ativa ou desativa o rastreamento de carregamentos (aberturas) e de cliques.
• "tracking": { "loads": true, "clicks": false } define cada um separadamente.

O rastreamento só funciona quando o CNAME de rastreamento do domínio está verificado. Sem ele, o e-mail é enviado sem rastreamento e a requisição é bem-sucedida mesmo assim. O objeto tracking da resposta mostra as configurações que foram de fato aplicadas. Consulte Rastreamento de aberturas e cliques.

Adicionar cabeçalhos e metadados

Use headers para cabeçalhos de e-mail personalizados, como List-Unsubscribe, e meta para os seus próprios pares chave-valor de strings. O Emailit armazena meta com o e-mail e o inclui nos eventos de webhook. Consulte Cabeçalhos e metadados.

Para anexar arquivos, agendar o envio ou tornar as novas tentativas seguras, consulte Anexos, Agendamento e Idempotência.

Ler a resposta

Uma requisição bem-sucedida retorna 200:

Guarde o id (ou o mapa ids) para associar os eventos de webhook que chegarem depois e consultar o e-mail com Obter um e-mail.

Eventos

O e-mail de cada destinatário emite os próprios eventos:

1. email.accepted logo após a requisição, ou email.scheduled se ele tiver um horário de envio no futuro.
2. Eventos de entrega à medida que o e-mail avança no processamento: email.delivered, email.attempted (falha temporária, haverá nova tentativa), email.bounced, email.failed, email.rejected ou email.suppressed. Um e-mail retido para análise emite email.held.
3. Eventos de engajamento, se o rastreamento estiver ativado: email.loaded e email.clicked. As denúncias de spam emitem email.complained.

Consulte Status de e-mail para saber o que cada status significa.

Erros

Os erros de validação retornam uma lista com todos os problemas encontrados:

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}

Um workspace suspenso recebe 403 com Workspace is suspended em todos os envios. Para o formato geral dos erros, consulte Erros.

Veja também

• Enviar um e-mail na referência da API
• Templates
• Status de e-mail
• Tipos de eventos de webhook
• Por que o meu e-mail não chegou?