Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

E-mails

Envie um e-mail ou um lote, agende e acompanhe do aceite até a entrega.

Um e-mail é uma requisição POST /emails, ou uma mensagem pelo relay SMTP. O BillionSend confere, guarda e devolve um id na hora. O envio acontece em segundo plano, então um 200 quer dizer que o e-mail foi aceito, não que foi entregue.

Enviar um e-mail

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.emails.send({
  from: "Acme <hello@mail.example.com>",
  to: ["user@example.org"],
  subject: "Welcome",
  html: "<p>Thanks for signing up.</p>",
});

A mesma chamada com curl:

curl -X POST https://api.billionsend.com/emails \
  -H "Authorization: Bearer $BILLIONSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.example.com>",
    "to": ["user@example.org"],
    "subject": "Welcome",
    "html": "<p>Thanks for signing up.</p>"
  }'
  • from: precisa estar em um domínio verificado da sua equipe.
  • to, cc, bcc, reply_to: um endereço ou uma lista. to, cc e bcc juntos têm no máximo 50 destinatários.
  • html e text: pelo menos um é obrigatório. Enviar com um id de template não é suportado. Um template é conteúdo que você copia para uma transmissão.
  • tags, headers, attachments: veja o básico da API para as regras, os limites de anexos e a idempotência.
  • topic_id: os destinatários que saíram desse tópico são pulados.

Para testar sem escrever a ninguém, envie para success@simulator.amazonses.com.

Enviar um lote

POST /emails/batch recebe um array de até 100 e-mails. Por padrão, um e-mail inválido faz o lote inteiro falhar. Adicione o cabeçalho x-batch-validation: permissive para aceitar os válidos: data lista os ids deles, e errors lista os outros por posição.

Agendar, alterar, cancelar

Adicione scheduled_at para enviar depois, até 30 dias à frente. Ele aceita um horário ISO 8601 com deslocamento, ou um horário relativo como in 2 hours. Enquanto o e-mail está agendado, PATCH /emails/{id} muda o horário e POST /emails/{id}/cancel o cancela.

Acompanhar um e-mail

GET /emails/{id} devolve o e-mail com last_event, o resultado mais recente, e um score dos Insights de entregabilidade. No painel, E-mails lista todos os e-mails e mostra os eventos de cada um em ordem. Corpos e histórico são guardados por 30 dias.

Evento Significado
email.scheduled Aceito, esperando o horário.
email.sent Entregue para o envio.
email.delivered O servidor do destinatário aceitou.
email.delivery_delayed A entrega está atrasada e será tentada de novo.
email.bounced O servidor do destinatário recusou.
email.complained O destinatário marcou como spam.
email.failed Não pôde ser enviado. O evento diz por quê.
email.suppressed Não foi enviado porque todos os destinatários estão suprimidos ou descadastrados.
email.opened, email.clicked O destinatário abriu ou clicou em um link, se o rastreamento estiver ligado.

Cada evento também pode ser enviado a você como webhook.

O que impede ou retém um envio

Um envio é recusado com um erro 4xx que nomeia o motivo quando:

  • o domínio do remetente não está verificado (422);
  • todos os destinatários estão suprimidos (422 all_recipients_suppressed);
  • você passou do volume do seu plano (429);
  • sua taxa de bounce ou de reclamação pausou o envio (403 sending_paused).

Alguns e-mails são aceitos mas retidos, e saem depois: um domínio novo acima do limite diário, ou e-mails esperando um limite reiniciar. Veja Limites de envio. A API e o relay SMTP aplicam as mesmas regras.

Esta página foi útil?