Broadcasts
Um broadcast envia um e-mail para toda uma audiência: uma newsletter, um comunicado ou qualquer conteúdo único que vai para muitos destinatários de uma vez. Os membros da audiência são resolvidos na lista de destinatários quando o envio começa, então o broadcast alcança quem for membro da audiência naquele momento.
Crie broadcasts em Email > Broadcasts no dashboard, pela API de broadcasts, com bird email broadcasts, ou pelo servidor MCP. Os SDKs de TypeScript, Python, Go e PHP oferecem um recurso broadcasts para todo o ciclo de vida: criar um rascunho, alterá-lo enquanto ainda for rascunho, enviá-lo agora ou em um horário futuro, listar os broadcasts do espaço de trabalho, consultar um com seus contadores, cancelar um que esteja agendado ou em envio, excluir um que ainda esteja em rascunho, e consultar seus destinatários, eventos, links clicados, a cota de envio que um envio consumiria e as contagens de audiência contra as quais um envio é resolvido. Para uma lista de destinatários avulsa, use envio em lote ou envios individuais.
Crie um rascunho
Comece na lista de Broadcasts com New broadcast. O compositor é uma página única: uma barra de audiência e remetente no topo, o conteúdo do e-mail abaixo, e um controle de configurações para categoria, rastreamento e tags. Não há etapa de salvamento separada. Toda alteração é salva automaticamente assim que o broadcast tem uma audiência e um remetente, então um rascunho existe assim que esses dois são definidos, e enviá-lo depois é uma ação separada e explícita.
Use o campo To para escolher uma audiência, ou selecione New para criar uma sem sair do compositor.
Abra o controle de configurações no cabeçalho do compositor para mais três itens:
- As chaves de rastreamento de abertura e clique.
- Até 20 tags, cada uma com um nome e um valor, para filtrar esse broadcast depois.
- A categoria, cujo padrão é
marketing.
O endereço de remetente
Um broadcast envia a partir de um endereço em um domínio de envio verificado. Combine uma parte local com um dos seus domínios verificados e adicione um nome de exibição se quiser. Adicione um endereço Reply-To se quiser direcionar as respostas para outro lugar. Selecionar Review avisa você se o domínio não estiver verificado.
O template
Um broadcast aponta para um dos templates de e-mail do seu espaço de trabalho, e o template contém o assunto e o corpo que o broadcast envia. As propriedades de contato de cada destinatário preenchem as variáveis do template quando o envio é executado, então um único broadcast personaliza o conteúdo por destinatário. Um broadcast só pode preencher propriedades de contato, então uma variável de template que referencia qualquer outra coisa é recusada quando você envia, e o erro nomeia a variável.
Escreva o conteúdo diretamente no canvas abaixo do assunto, ou selecione Choose a template para começar a partir de um existente. Essa opção só fica disponível enquanto o broadcast está em branco, já que escolher um template depois de ter escrito um assunto ou corpo o sobrescreveria. Um broadcast envia a versão publicada do template, então um template que só tem rascunho não pode sustentar um envio.
Um template com mais de um idioma envia um deles para toda a audiência. Informe-o como template.language ao criar ou atualizar o broadcast, e omita-o para enviar o idioma padrão do template. Alterar apenas o idioma mantém o broadcast na versão à qual ele está fixado, quando já tiver uma. Um broadcast é fixado a uma versão quando é preparado para envio, então um broadcast agendado envia a versão publicada naquele momento, independentemente de você alterar o idioma antes disso.
Enviar ou agendar
Em breve: A espera por fundos e os controles para retomar descritos abaixo ainda não estão disponíveis. Um broadcast que fica sem fundos falha com quota_exceeded. Use Consultar um broadcast para verificar failure_detail e adicione fundos se ele indicar falta de saldo. Uma recarga não reinicia um broadcast que falhou; antes de criar outro envio, verifique a quais destinatários a mensagem não foi enviada. Uma mensagem aceita para entrega, mas ainda adiada, já foi enviada; exclua esse destinatário do novo broadcast.
O envio é uma ação separada e explícita, disponível pelo botão Review do compositor ou pela página de detalhes do broadcast em Send or reschedule. Cada um abre um diálogo que verifica se o broadcast está completo, avisa sobre qualquer coisa que possa causar falha no envio e permite escolher Send now ou selecionar um horário com até um ano de antecedência. Um broadcast agendado permanece editável, e você pode reagendá-lo até o momento em que o envio realmente começa.
O envio verifica se a audiência ainda tem alguém para alcançar. Uma audiência em que ninguém tem endereço de e-mail, ou em que todos os endereços estão suprimidos, é recusada nesse momento em vez de falhar depois.
Dois limites no nível da organização são verificados quando você envia.
O primeiro é quantos broadcasts você pode enviar em um período de cobrança, quando seu plano define um número. Rascunhos salvos não contam, e cancelar um broadcast não devolve a cota. Depois que você a usa toda, ou espera o próximo período de cobrança ou muda para um plano com limite maior.
O segundo limita broadcasts simultâneos. Se você seleciona Send now enquanto o limite está atingido, a solicitação é rejeitada. Um broadcast agendado aguarda uma vaga livre.
Antes de enviar, revise no diálogo Send o custo estimado para os destinatários que podem receber o broadcast e qualquer aviso de cota. Membros com acesso à cobrança também veem o saldo da carteira e se a recarga automática está ativada. O custo inclui impostos quando há um preço disponível; preços e uso podem mudar antes do envio. Se o seu plano não tem estimativa para broadcasts, o diálogo informa isso em vez de mostrar custo zero. A cota é uma estimativa compartilhada com outros envios de e-mail. Agendar um broadcast não reserva o saldo dele, e outro broadcast pode usar os fundos antes que este termine.
Se a recarga automática estiver ativada, suas configurações atuais podem cobrar seu método de pagamento salvo mais de uma vez durante o envio do broadcast. Iniciar um broadcast não aumenta o valor da recarga nem autoriza um pagamento separado para toda a audiência.
Se o saldo acabar, o broadcast mostra Waiting for funds por até 20 minutos, com ou sem recarga automática ativada. Ele verifica uma vez por minuto se há fundos disponíveis. Adicionar fundos manualmente ou por recarga automática pode reiniciar o envio durante esse período. Uma recarga que deixe sua conta bloqueada por fundos insuficientes não reinicia o envio. Recargas parciais não prolongam a espera atual. Depois que o envio é retomado, uma interrupção posterior inicia uma nova espera de 20 minutos.
Se a espera terminar antes que o envio possa continuar, o broadcast passa a Paused e os contatos de cobrança da sua organização recebem um e-mail. Verifique o saldo e adicione fundos se necessário. Broadcasts em espera mantêm sua vaga de envio simultâneo; broadcasts pausados a liberam.
Abra o broadcast e selecione Resume broadcast. Confirme que as datas, ofertas e prazos dele ainda são válidos: os destinatários restantes vão receber a mensagem mais tarde do que o previsto.
No diálogo Resume broadcast, expanda Preview email para revisar um template salvo no espaço de trabalho. A pré-visualização exige email_management:read; se você não tiver essa permissão, peça a um colega autorizado que o revise. Templates integrados e conteúdo salvo que esteja ausente não podem ser pré-visualizados aqui. Se a pré-visualização não estiver disponível, siga as verificações do template abaixo e deixe o broadcast pausado até poder verificar o que os destinatários restantes receberão. A pré-visualização é opcional e não impede a retomada.
Para um broadcast iniciado há pelo menos 24 horas, a confirmação mostra a idade dele em horas e um aviso sobre entrega atrasada. Adicionar fundos não retoma automaticamente um broadcast pausado.
Para revisar a mensagem antes de retomar pela API, consulte o broadcast e leia as referências started_at e template fixadas. Consulte o template usando template.id; scope: system identifica um template integrado. Se a consulta do template retornar 404, tente a versão fixada pelo ID, porque as versões publicadas do espaço de trabalho continuam legíveis depois da exclusão. Para um template do espaço de trabalho, consulte essa versão do template com template.id como template_ref e template.version_id como version_id. Revise o assunto e o corpo em template.language, ou em default_language da versão se nenhum idioma foi selecionado. Ler esse conteúdo exige email_management:read; se você não tiver essa permissão, peça a um colega autorizado que o revise. As consultas de templates integrados mostram o conteúdo atual do catálogo. Broadcasts com conteúdo congelado o mantêm, mas broadcasts mais antigos podem ler o catálogo novamente ao serem retomados. Nem uma consulta atual nem uma mensagem anterior, sozinhas, comprovam o que os destinatários restantes vão receber. Mantenha o broadcast pausado, a menos que você consiga verificar esse conteúdo.
A API de retomada e os SDKs exigem confirm: true para um broadcast com essa idade. Com a CLI, revise o broadcast primeiro e depois passe --yes para bird email broadcasts resume para confirmar a entrega atrasada. A CLI retorna um aviso sem essa flag e não faz perguntas interativas. A ferramenta de retomada do MCP também usa confirm: true; peça à pessoa que solicitou o envio que confirme que a mensagem ainda é oportuna.
Chamadas programáticas sempre podem passar confirm: true, inclusive antes do limite de 24 horas, se a aplicação já decidiu continuar a entrega. Isso não pula as verificações de saldo, cota de envio, permissão ou broadcasts simultâneos.
A seleção de Brand está disponível em prévia. Um broadcast mantém o brand_id selecionado enquanto aguarda saldo, está pausado ou é retomado. As preferências de consentimento da Brand e as proteções de todo o espaço de trabalho continuam valendo. A Brand não pode ser arquivada até que o broadcast termine ou seu cancelamento seja concluído.
Ao retomar, as referências de template salvas e a lista de destinatários são mantidas. Os destinatários para os quais a mensagem já foi enviada não a recebem novamente. As supressões e preferências de consentimento atuais se aplicam conforme a categoria do broadcast: cancelamentos de inscrição em marketing não bloqueiam broadcasts transacionais. Retomar não consome outro broadcast da sua cota mensal. Sua conta não pode mais estar bloqueada por fundos insuficientes, a cota de envio precisa cobrir o próximo lote e deve haver uma vaga de envio simultâneo disponível. Se um limite diário ou mensal de envio ainda bloquear o lote, a retomada retorna 429 e mantém o broadcast pausado. Tente novamente com o mesmo broadcast depois que a cota for renovada ou o limite mudar. Um espaço de trabalho suspenso retorna 403 com E08024. Depois da reativação, um broadcast autorizado antes da suspensão continua sem poder ser retomado: a API retorna 403 com E04102. Cancele esse broadcast em vez de tentar novamente. Não reenvie para a audiência inteira sem excluir os destinatários aos quais a mensagem já foi enviada. Retomar não reserva fundos nem garante que todas as mensagens restantes possam ser enviadas. Se o saldo acabar após uma retomada explícita, começa uma nova espera de 20 minutos. Se a mensagem não for mais útil, você pode cancelar o broadcast.
Encontrar um broadcast
Pesquise a lista por tag ou nome de template, ou filtre por status, audiência ou intervalo de datas. O intervalo de datas filtra pela data de criação de cada broadcast, não pela data de envio. Assim, um broadcast que você agendou na semana passada para envio no mês que vem ainda aparece em "Last 7 days."
Exporte a visualização atual como CSV pelo botão acima da tabela, ou chame Exportar broadcasts como CSV, que aceita os mesmos filtros. Acima de 50.000 linhas, a exportação é recusada em vez de cortada silenciosamente. Restrinja os filtros e tente novamente.
Status do broadcast
Em breve: Os status waiting_for_funds e paused abaixo ainda não estão disponíveis. Atualmente, um broadcast que fica sem fundos falha e não é retomado após uma recarga.
O estágio de um broadcast aparece no filtro Status:
| Estágio | Onde o broadcast está | Valores de status |
|---|---|---|
| Rascunho | Salvo sem compromisso de envio | draft |
| Agendado | Confirmado com horário de envio futuro, ainda editável | scheduled |
| Enviando | A caminho, aguardando fundos ou sendo cancelado | accepted, sending, waiting_for_funds, canceling |
| Pausado | Interrompido por falta de fundos, aguardando você retomar | paused |
| Concluído | Finalizado, seja enviado, cancelado ou com falha | sent, canceled, failed |
O badge de cada linha mostra o status exato dentro do estágio. Esse mesmo valor é o que o campo status da API retorna.
Cancelar ou excluir
Cancele um broadcast agendado, em envio, aguardando fundos ou pausado pela página de detalhes, com bird email broadcasts cancel, ou com Cancelar um broadcast e o método broadcasts.cancel SDK. Destinatários ainda não alcançados são ignorados, e qualquer mensagem já a caminho não pode ser revogada. A exclusão funciona apenas em rascunhos e é permanente, pelas mesmas três vias: a página de detalhes, bird email broadcasts delete, ou Excluir um broadcast.
Quando um broadcast falha
O dashboard explica a falha e o que verificar em seguida. Para quota_exceeded, ele mostra o motivo registrado e orientações sobre limites de envio e fundos. Você também pode usar Consultar um broadcast e ler failure_reason e failure_detail.
A configuração de envio de um broadcast é verificada somente quando o envio começa. Se o domínio de envio estava verificado no agendamento, mas perdeu a verificação antes do envio, o broadcast falha nesse momento. Verifique o domínio e envie o broadcast novamente.
failure_reason | O que aconteceu | O que fazer |
|---|---|---|
content_invalid | Não foi possível preparar o broadcast para envio. A causa geralmente está na configuração, não no conteúdo: um domínio de envio não verificado, um template ausente ou não publicado, um template com loop, ou um pool de IPs indisponível | Corrija o que failure_detail indica e envie novamente |
empty_audience | A audiência não tem membros, ou as supressões excluem todos os membros | Adicione membros ou verifique suas supressões |
audience_unavailable | A audiência não existe mais | Aponte o broadcast para outra audiência |
quota_exceeded | O envio atingiu um limite diário ou mensal de e-mails, um teto de excedente, outro limite de envio ou uma falta de saldo | Verifique sua cota de envio e seu saldo. Use o detalhe API para identificar uma falta de saldo registrada; adicione fundos se necessário, ou aguarde a cota ser renovada, reduza a audiência ou revise o plano |
insufficient_funds | O saldo do espaço de trabalho não cobriu o envio | Recarregue a carteira |
internal_error | Algo deu errado do nosso lado | Tente novamente e abra um ticket de suporte se o erro se repetir |
workspace_suspended | O espaço de trabalho está suspenso, então o broadcast parou de enviar. Os destinatários ainda não alcançados não recebem a mensagem, mesmo depois que o espaço de trabalho é reativado | Entre em contato com o suporte para reativar o espaço de trabalho. A aba Recipients mostra quem foi alcançado |
Broadcasts e envios individuais compartilham a cota de e-mails da organização. Adicionar fundos não reinicia um broadcast que falhou. Antes de criar outro broadcast, verifique a quais destinatários a mensagem não foi enviada. Exclua os destinatários cujas mensagens foram aceitas para entrega, incluindo mensagens ainda adiadas pelo servidor de destino. O comportamento de espera e pausa chega em breve. Limites rígidos de envio e restrições de pagamento continuam valendo. Planos e preços descreve o que cada plano inclui.
Acompanhar a entrega
Assim que o envio começa, a aba Overview do broadcast mostra os contadores de destinatários e enviados, e depois as taxas de entrega, abertura, clique, bounce e reclamação com seus respectivos contadores. A aba Recipients lista cada destinatário com seu status de entrega, o motivo caso não tenha sido entregue, a data de entrega e suas aberturas e cliques. A caixa de busca exige um endereço de e-mail completo e válido; um endereço parcial ou apenas um domínio falha na validação, marca a caixa como inválida e mantém a tabela exibindo o que já estava. Um botão acima da tabela exporta a aba como CSV, e Exportar destinatários de um broadcast como CSV retorna o mesmo arquivo para uma chave API; ambos têm limite de 500.000 linhas, com o mesmo comportamento de recusar em vez de truncar da exportação da lista de broadcasts. A aba Events é o feed bruto de eventos do broadcast, usando os tipos de evento descritos em eventos e webhooks.
Ensaiar um broadcast
Coloque um endereço sandbox na audiência e esse contato será simulado em vez de receber o envio: delivered@messagebird.dev reporta como entregue, bounce@messagebird.dev como bounce, e cada um produz os mesmos eventos e webhooks que um destinatário real produziria. É assim que você exercita uma campanha, e o handler que lê seus eventos, sem enviar e-mail para ninguém. Uma audiência pode misturar contatos sandbox e reais; cada contato recebe seu próprio resultado. Um destinatário simulado ainda conta na sua cota de envio, então o ensaio consome a mesma cota que o envio real consumiria.
Próximos passos
- Audiências: as listas de destinatários para as quais um broadcast envia
- Templates de e-mail: o assunto e o corpo para os quais um broadcast aponta
- Métricas de e-mail: a visão geral do espaço de trabalho alimentada pelos broadcasts
bird email broadcasts: um comando CLI por operação de broadcast- Criar um broadcast: a referência API, com schemas completos de requisição e resposta e um exemplo de código por SDK
- Envios de email em massa: um email para toda a sua audiência: um vídeo que envia um broadcast e lê seus resultados
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.