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

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}/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.

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).

  • 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-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:

{
  "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.
  • 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.

Esta página foi útil?