Transmissões
Componha, agende e envie um e-mail para muitos contatos.
Uma transmissão (/broadcasts na API) é um e-mail enviado a muitos contatos: todos eles, um segmento ou um tópico. Componha no painel, em Transmissões, com campos de mesclagem por contato, ou crie pela API.
Enviar uma transmissão
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 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}/senda envia agora ou emscheduled_at.POST /broadcasts/{id}/cancelcancela uma transmissão agendada, ou uma que já está saindo. Os e-mails já enviados não voltam. Ocanceled_remainingda resposta diz quantos foram parados, e osent_countde uma leitura diz quantos saíram.- Rascunhos, e transmissões com falha que não enviaram nada, podem ser excluídos.
- Na API,
scheduledesendingaparecem os dois comoqueued. Uma transmissão aparece comoqueuedcomsent_atvazio até o último e-mail sair.
Quem recebe
Cada destinatário é conferido quando a transmissão sai. Ficam de fora:
- contatos
unsubscribedpara 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.
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.
- Como o destinatário vê. O link de descadastro abre a página de descadastro 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. - Todo e-mail de transmissão recebe cabeçalhos
List-Unsubscribede 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:
{
"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.warningaparece quando o envio leva mais de uma onda:pacedquando o público é maior que a capacidade disponível agora,queued_behindquando outros envios vêm antes.- Enquanto sai,
GET /broadcasts/{id}traz umfinishes_ate umsent_countao 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.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.
Veja a referência da API para todos os endpoints de transmissões.