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,ccebccjuntos têm no máximo 50 destinatários.htmletext: 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.