Broadcasts

Um broadcast é um email enviado a muitos contatos: todos eles, um segmento ou um tópico. Componha no editor de blocos do painel (com campos de mesclagem por contato) ou crie broadcasts pela API.

Ciclo de vida

draft → scheduled → sending → sent
              ↘ canceled

• Broadcasts são criados como rascunhos (draft). Só rascunhos podem ser editados ou apagados.
• POST /broadcasts/{id}/send agenda o envio — imediatamente, ou em um timestamp scheduled_at.
• Um broadcast na fila — agendado, ou já saindo — pode ser cancelado com POST /broadcasts/{id}/cancel. 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 já tinham saído.
• Na comunicação, scheduled e sending aparecem ambos como queued (correspondendo à união de status do SDK do Resend); canceled é uma extensão do MillionSend. Um broadcast aparece como queued com sent_at nulo até o último e-mail sair, leve o tempo que levar.

O que o fan-out faz

Cada email de destinatário passa pelo mesmo pipeline de um envio transacional, mais o tratamento específico de broadcast:

• Resolução de audiência — contatos descadastrados globalmente são sempre excluídos; filtros de segmento e inscrições em tópicos são avaliados no momento do envio.
• Checagens de supressão — endereços na lista de supressão são pulados.
• Campos de mesclagem — valores por contato (nome, propriedades customizadas) são substituídos no template.
• Links de descadastro — headers List-Unsubscribe de um clique (RFC 8058) e um link de descadastro hospedado são adicionados a cada mensagem. Para colocar o link no corpo, escreva {{{UNSUBSCRIBE_URL}}} — ele é substituído por destinatário pela URL de descadastro hospedada. {{{RESEND_UNSUBSCRIBE_URL}}} é um alias suportado, então templates escritos para o Resend continuam funcionando sem mudança (e voltam sem mudança).

Os e-mails de broadcast entram na fila de envio abaixo dos transacionais: um e-mail transacional aceito enquanto um broadcast está saindo é enviado antes dos destinatários restantes. Os envios rodam em várias pistas ao mesmo tempo, no ritmo da taxa de envio do SES da instância.

Ritmo de envio

A plataforma envia uma quantidade limitada de e-mails por dia. Um broadcast que cabe no que está disponível sai de uma vez, na taxa de envio. Um maior sai em levas: a primeira agora, o restante conforme a capacidade libera nos dias seguintes. E-mails transacionais nunca ficam retidos atrás de um broadcast.

O envio avisa de antemão:

{
  "id": "8c1f0b8e-…",
  "finishes_at": "2026-09-18T13:26:05Z",
  "estimated": true,
  "warning": {
    "code": "paced",
    "days": 3,
    "message": "170,000 recipients exceed the broadcast capacity available now; sending is paced and finishes about 2026-09-18T13:30:00Z. Transactional email is unaffected."
  }
}

• finishes_at é o instante estimado em que o último e-mail sai; null quando não há estimativa. É uma estimativa: outros envios a movem.
• warning só aparece quando o envio leva mais de uma leva — paced quando a audiência passa da capacidade disponível agora, queued_behind quando outros envios estão na frente (a mensagem diz quando este começa).
• Enquanto um broadcast está saindo, GET /broadcasts/{id} e a lista trazem finishes_at ao vivo e sent_count.
• Uma audiência que precisaria de mais de 24 dias de capacidade — da plataforma, ou do limite do seu plano — é recusada com 422 broadcast_too_large em vez de aceita e deixada esperando. Divida em segmentos menores ou fale com o suporte.

Salvaguardas

• Somente um domínio verificado do seu time pode aparecer em from.
• Se sua taxa recente de bounce ou reclamação cruzou o limite de pausa do SES, novos envios de broadcast são bloqueados com um erro 403 sending_paused — contendo o estrago antes que o SES pause o envio por completo.
• Se a taxa agregada de bounce ou reclamação da plataforma na região SES do seu remetente se aproxima da linha de revisão do SES, envios de broadcast nessa região são recusados com 403 broadcasts_paused até a taxa se recuperar. O e-mail transacional continua saindo, e a pausa libera sozinha.

Veja a referência da API para todos os endpoints de broadcast.

Mudanças recentes

• Um broadcast com e-mails ainda esperando — por capacidade, ou pela virada do limite do plano — aparece como queued com sent_at nulo até o último e-mail sair. Antes aparecia como sent assim que todos os e-mails eram gravados.
• Uma audiência cujo limite do plano precisaria de mais de 24 dias é recusada com 422 broadcast_too_large em vez de aceita e deixada esperando.
• POST /broadcasts/{id}/cancel funciona em um broadcast que já está saindo; a resposta traz canceled_remaining.