---
title: Transmissões
description: Componha, agende e envie um e-mail para muitos contatos.
ai:
  exclude: true
---

Uma transmissão (`/broadcasts` na API) é um e-mail enviado a muitos contatos: todos eles, um [segmento](/docs/pt-br/concepts/segments) ou um [tópico](/docs/pt-br/concepts/topics). Componha no painel, em **Transmissões**, com campos de mesclagem por contato, ou crie pela API.

## Enviar uma transmissão

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

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

const { data, error } = await bs.broadcasts.create({
  name: "November news",
  segment_id: "SEGMENT_ID",
  from: "Acme <news@mail.example.com>",
  subject: "What's new",
  html: "<p>Hi {{{FIRST_NAME|there}}},</p><p>...</p><p><a href=\"{{{UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>",
});

if (error) throw error;

await bs.broadcasts.send(data.id, { scheduled_at: "in 1 hour" });
```

Deixe `scheduled_at` de fora para enviar agora. Uma transmissão precisa de um domínio de envio verificado em `from`. No compositor, você pode partir de um [template](/docs/pt-br/concepts/templates) salvo.

## Ciclo de vida

```
draft → scheduled → sending → sent
              ↘ canceled
              ↘ failed
```

- Uma transmissão nova é um **rascunho**, e só um rascunho pode ser editado.
- `POST /broadcasts/{id}/send` a envia agora ou em `scheduled_at`.
- `POST /broadcasts/{id}/cancel` cancela uma transmissão agendada, ou uma que já está saindo. Os e-mails já enviados não voltam. O `canceled_remaining` da resposta diz quantos foram parados, e o `sent_count` de uma leitura diz quantos saíram.
- Rascunhos, e transmissões com falha que não enviaram nada, podem ser excluídos.
- Na API, `scheduled` e `sending` aparecem os dois como `queued`. Uma transmissão aparece como `queued` com `sent_at` vazio até o último e-mail sair.

## Quem recebe

Cada destinatário é conferido quando a transmissão sai. Ficam de fora:

- contatos `unsubscribed` para a equipe inteira e contatos que se descadastraram do domínio de envio da transmissão;
- contatos que saíram do tópico da transmissão;
- endereços na [lista de supressão](/docs/pt-br/concepts/suppressions).

A contagem de destinatários que o painel mostra antes do envio já deixa esses contatos de fora.

## O domínio de envio

O domínio de envio da transmissão é o do endereço `from`, devolvido como `domain_id`. Ele decide:

- **De quem valem os descadastros.** Quem se descadastrou desse domínio é pulado. Veja [Marcas e descadastros](/docs/pt-br/concepts/unsubscribes).
- **Como o destinatário vê.** O link de descadastro abre a [página de descadastro](/docs/pt-br/concepts/unsubscribes) própria do domínio, no subdomínio dele quando há um.
- **Qual público é permitido.** Um tópico ou segmento vinculado a outro domínio é recusado com `422`, para que uma marca nunca escreva ao público de outra.

Um domínio não pode ser excluído enquanto uma transmissão agendada ou em envio o usa (`409`).

## Campos de mesclagem e links de descadastro

- Valores por contato como `{{{FIRST_NAME|there}}}` são preenchidos para cada destinatário. Veja [Templates](/docs/pt-br/concepts/templates).
- Todo e-mail de transmissão recebe cabeçalhos `List-Unsubscribe` de um clique e um link de descadastro hospedado. Para colocar o link no corpo, escreva `{{{UNSUBSCRIBE_URL}}}`.

## Ritmo

Uma transmissão que cabe na capacidade disponível sai logo. Uma maior sai em ondas ao longo dos dias seguintes. O e-mail transacional nunca fica preso atrás de uma transmissão: ele sai antes dos destinatários restantes de uma transmissão.

A chamada de envio diz o que esperar:

```json
{
  "id": "8c1f0b8e-…",
  "finishes_at": "2026-09-18T13:26:05Z",
  "estimated": true,
  "warning": { "code": "paced", "days": 3, "message": "…" }
}
```

- `finishes_at` é o horário estimado em que o último e-mail sai. É uma estimativa, e outros envios podem movê-la.
- `warning` aparece quando o envio leva mais de uma onda: `paced` quando o público é maior que a capacidade disponível agora, `queued_behind` quando outros envios vêm antes.
- Enquanto sai, `GET /broadcasts/{id}` traz um `finishes_at` e um `sent_count` ao vivo.
- Um público que precisaria de mais de 24 dias de capacidade é recusado com `422 broadcast_too_large`. Divida-o em segmentos menores.

## Duplicar uma transmissão

`POST /broadcasts/{id}/duplicate` copia qualquer transmissão, até uma já enviada ou com falha, para um novo rascunho. No painel, use **Duplicar** no menu da transmissão.

- **Copiado:** segmento, tópico, remetente, assunto, `reply_to`, texto de pré-visualização e conteúdo.
- **Não copiado:** o agendamento, as contagens e o progresso da entrega. A cópia é um rascunho comum.
- O nome é o do original seguido de ` (copy)`.

## Quando uma transmissão falha

Uma transmissão termina `failed` quando foi aceita mas não pode sair, ou quando o envio continuou falhando. `GET /broadcasts/{id}` então devolve `failure_reason` e `failed_at`. Os e-mails já entregues para o envio continuam enviados, e os proprietários da equipe recebem um e-mail uma vez.

| `failure_reason` | Significado |
| --- | --- |
| `domain_missing` | O domínio de envio foi excluído. |
| `sender_domain_mismatch` | O `from` não está mais no domínio com que a transmissão foi agendada. |
| `topic_other_domain` | O tópico está vinculado a outro domínio. |
| `segment_other_domain` | O segmento está vinculado a outro domínio. |
| `domain_unverified` | O domínio de envio ficou sem verificação durante algumas horas de novas tentativas. |
| `retries_exhausted` | Outro erro continuou falhando até as novas tentativas acabarem. |

Para alcançar o público, duplique a transmissão, corrija a causa no novo rascunho e envie.

## Quando uma transmissão é recusada

- `403 sending_paused`: sua taxa de bounce ou de reclamação está alta demais. Veja [Limites de envio](/docs/pt-br/concepts/sending-limits).
- `403 broadcasts_paused`: as transmissões estão em pausa, na plataforma inteira enquanto as taxas se recuperam ou só na sua equipe, pelo BillionSend. O e-mail transacional não é afetado.
- `403 inbox_send_policy`: o remetente está no domínio compartilhado das suas caixas de entrada, que não pode enviar transmissões.

Quando uma transmissão chega ao volume do seu plano, o resto do público espera e sai quando houver espaço. Veja [Planos e limites](/docs/pt-br/billing).

Veja a [referência da API](/docs/pt-br/api-reference) para todos os endpoints de transmissões.
