---
title: E-mails
description: Envie um e-mail ou um lote, agende e acompanhe do aceite até a entrega.
ai:
  exclude: true
---

Um e-mail é uma requisição `POST /emails`, ou uma mensagem pelo [relay SMTP](/docs/pt-br/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

```ts
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`:

```bash
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](/docs/pt-br/concepts/domains) 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](/docs/pt-br/concepts/templates) é conteúdo que você copia para uma transmissão.
- `tags`, `headers`, `attachments`: veja o [básico da API](/docs/pt-br/api-reference/basics) para as regras, os limites de anexos e a idempotência.
- `topic_id`: os destinatários que saíram desse [tópico](/docs/pt-br/concepts/topics) 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](/docs/pt-br/concepts/deliverability-insights). 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](/docs/pt-br/concepts/tracking) estiver ligado. |

Cada evento também pode ser enviado a você como [webhook](/docs/pt-br/concepts/webhooks).

## 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](/docs/pt-br/concepts/suppressions) (`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](/docs/pt-br/concepts/sending-limits). A API e o relay SMTP aplicam as mesmas regras.
