> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Campanhas de broadcast

> Envie uma campanha de email para uma lista de contatos, com filtros de segmento, teste A/B, rastreamento UTM e agendamento.

![A página Broadcasts, com os resultados dos últimos 30 dias e, para cada broadcast, a audiência, os destinatários, as aberturas e os cliques](https://www.notifuse.com/docs/assets/screenshots/broadcast.png)

A página **Broadcasts** lista suas campanhas com os resultados dos últimos 30 dias: emails enviados, taxas de abertura e de clique, cancelamentos de inscrição e retornos. As abas filtram por status (Rascunhos, Agendado, Enviando, Enviado e Falhou, quando algum broadcast tem destinatários com falha) e mostram quantos broadcasts cada uma tem; a busca encontra um broadcast pelo nome. Cada linha mostra a audiência, o horário de envio ou de agendamento, os destinatários (uma estimativa antes do envio), as aberturas, os cliques, os cancelamentos de inscrição, os retornos e as visitas ao site que ele trouxe, se você usa [web analytics](https://www.notifuse.com/pt/docs/web-analytics/setup.md). Um rascunho abre no editor, e qualquer outro broadcast abre nos resultados. Dentro de um broadcast aberto, `J` e `K` levam ao próximo e ao anterior.

## Segmentação da audiência

A audiência de um broadcast é uma lista de contatos, que pode ser restringida por segmentos dinâmicos.

### Selecionar uma lista

Cada broadcast tem como alvo exatamente uma lista de contatos. O histórico de mensagens e os cancelamentos de inscrição são registrados por lista, e como um contato aparece uma única vez em cada lista, não há duplicatas para tratar.

Por exemplo, envie o anúncio de um produto para a sua lista "Newsletter Subscribers".

### Avisos para todos os membros

Por padrão, um broadcast deixa de fora os contatos da lista que cancelaram a inscrição. Para um aviso que todos os membros precisam receber (segurança, indisponibilidade ou questão legal), desative **Excluir destinatários que cancelaram a inscrição**. Os contatos que cancelaram a inscrição também o recebem, e os emails saem sem o cabeçalho `List-Unsubscribe`, então os clientes de email não mostram o botão de cancelar a inscrição. Contatos com retorno ou reclamação continuam sem receber nenhum email, e o link de cancelamento do seu template fica como está. Os status de inscrição estão em [Listas](https://www.notifuse.com/pt/docs/features/lists.md).

### Filtros de segmento

Os filtros de segmento restringem a lista aos contatos dos seus segmentos. Um segmento pode filtrar por:

- Propriedades do contato, como país, idioma ou qualquer campo personalizado
- Atividade de email: emails enviados, abertos, clicados ou com retorno
- Metas, como compras, cadastros ou leads, contadas ou somadas pelo valor

Um broadcast que indica vários segmentos envia para os contatos que estão em pelo menos um deles. Para exigir várias condições ao mesmo tempo, combine-as com AND dentro de um único segmento.

O Notifuse calcula antecipadamente quem pertence a cada segmento e mantém isso atualizado em segundo plano (veja [Contatos](https://www.notifuse.com/pt/docs/features/contacts.md#contact-segmentation-engine)). Um broadcast lê os membros atuais no momento do envio.

#### Exemplos de filtros de segmento

- Clientes de alto valor: a lista "All Customers" com um segmento cuja condição de **Meta** é um **total** de **Compra** de 1000 ou mais
- Reengajamento: a lista "Newsletter" com um segmento dos contatos que não abriram nenhum email nos últimos 90 dias
- Campanha geográfica: "All Contacts" com um segmento em `country = "US"` AND `state = "California"`
- Clientes fiéis: um segmento cuja condição de **Meta** conta pelo menos 3 metas de **Compra**, para recompensá-los

Quando um broadcast tem uma lista e filtros de segmento, só o recebem os contatos que pertencem à lista E a pelo menos um dos segmentos.

## Remetente

Um broadcast sempre envia pela integração de email de marketing do workspace. Por padrão, cada email sai com o remetente do template, ou com o remetente padrão da integração quando o template não tem um.

Para enviar uma campanha de outro endereço sem editar o template, escolha um **Remetente** ao lado do template, no card **Conteúdo** do editor de broadcast. Só aparecem os remetentes da integração de email de marketing; ao limpar o campo, o broadcast volta ao remetente do template. Pela API, defina `sender_id` na variação, em `test_settings.variations`.

Um remetente escolhido no broadcast nunca é trocado por outro endereço (já o remetente próprio de um template, se for removido, dá lugar ao padrão da integração):

- Um remetente que não pertence à integração é recusado quando o broadcast é salvo.
- Se o remetente escolhido for removido da integração depois, os destinatários restantes daquela variação não entram na fila até que você escolha outro. O broadcast não pode ser agendado, nem retomado enquanto essa variação ainda tiver destinatários para enfileirar.
- Um broadcast que está enfileirando os destinatários dessa variação quando o remetente é removido pausa antes do lote seguinte. Clique em **Alterar remetente**, ao lado de **Retomar**, no broadcast pausado, escolha outro remetente e retome o envio.
- Em um teste A/B, depois que o vencedor é escolhido, o remetente removido de uma variação perdedora não trava mais o broadcast. Ele continua sendo verificado sempre que as variações são salvas, então a caixa **Alterar remetente**, quando aparece, também pede um novo remetente para ela.
- Os emails que já estão na fila mantêm o remetente com que foram enfileirados, inclusive depois de retomar. Um broadcast com todos os destinatários já na fila não oferece **Alterar remetente**, porque um novo remetente não mudaria nada.

## Teste A/B

Um teste A/B envia várias variações para uma amostra da audiência e compara os resultados.

### Configuração do teste

- A amostra do teste é uma porcentagem dos seus destinatários.
- As variações podem ter assunto, conteúdo ou template diferentes.
- Cada variação mantém o remetente do seu template ou escolhe outro, então o remetente também pode fazer parte do teste.
- A amostra é dividida igualmente entre as variações.

![A seção Conteúdo de um broadcast com teste A/B ativado: duas variantes, a amostra do teste e o vencedor enviado automaticamente pela taxa de abertura após 4 horas](https://www.notifuse.com/docs/assets/screenshots/broadcast_ab_test.png)

### Escolha do vencedor

#### Escolha manual

Analise os resultados de cada variação e escolha o vencedor você mesmo; o Notifuse o envia para o restante da audiência.

#### Escolha automática

O Notifuse pode escolher o vencedor sozinho, pela maior taxa de abertura ou pela maior taxa de cliques, medida durante um período definido por você (por exemplo, 2 horas ou 24 horas). Ao fim desse período, ele envia a variação vencedora para o restante da audiência.

As taxas são calculadas sobre os destinatários cujas aberturas ou cliques foram rastreados, o que depende do [consentimento de rastreamento](https://www.notifuse.com/pt/docs/features/email-tracking.md) de cada um. Um broadcast enviado sem rastreamento não consegue escolher o vencedor automaticamente.

### Pausar ou cancelar um teste

Um teste A/B pode ser pausado ou cancelado em qualquer etapa: durante o envio da amostra, na espera pelo vencedor e durante o envio do vencedor. Ao ser retomado, ele continua na etapa em que parou: um teste que esperava o vencedor volta a esperar, e um vencedor que estava sendo enviado segue para o restante da audiência. O tempo em pausa durante a espera pelo vencedor não conta na duração do teste; o vencedor automático é escolhido quando a duração se completa, sem contar a pausa. Cancelar remove os emails que ainda aguardavam envio, e nada mais é enviado.

Um broadcast agendado com teste A/B roda o teste no horário agendado, como um enviado na hora: primeiro a amostra, depois o vencedor.

### Exemplo de teste A/B

1. Crie uma campanha com 2 variações de assunto
2. Defina a amostra do teste em 20% da audiência
3. Configure a escolha automática do vencedor pela taxa de abertura após 4 horas
4. O Notifuse envia a variação vencedora para os 80% restantes

## Rastreamento UTM

### Parâmetros UTM automáticos

O Notifuse adiciona parâmetros UTM a todos os links externos dos seus templates de email:

- **utm_source**: a origem do email
- **utm_medium**: "email" em todas as campanhas de broadcast
- **utm_campaign**: o nome da sua campanha
- **utm_content**: o ID do template

### Exemplo de UTM

**Link original**: `https://yourwebsite.com/products`

**Com parâmetros UTM**:

```
https://yourwebsite.com/products?utm_campaign=summer_sale_2024&utm_content=summer_sale_template&utm_medium=email&utm_source=notifuse
```

### Enviar sem rastrear aberturas e cliques

Marque **Não rastrear aberturas e cliques neste broadcast** para enviá-lo sem pixel de rastreamento e sem redirecionamento de cliques, para todos os destinatários. Os parâmetros UTM são mantidos. Sem essa opção, vale o [consentimento de rastreamento](https://www.notifuse.com/pt/docs/features/email-tracking.md) de cada destinatário.

### Estatísticas por link

O painel **Links clicados** dos resultados de um broadcast lista cada link clicado com os cliques únicos, a taxa de cliques e o total de cliques, para todas as variações ou para uma delas. **Ver quem clicou**, em cada linha, abre o [log de mensagens](https://www.notifuse.com/pt/docs/features/logs.md#filtering-options) filtrado nos emails
em que o link foi clicado. Para agir sobre esses cliques, por exemplo para adicionar os contatos a uma lista, use o
gatilho de automação [Clicou em um link](https://www.notifuse.com/pt/docs/features/automations.md#link-click-triggers).

![O painel Links clicados de um broadcast enviado: cada link com os cliques únicos, a taxa de cliques e o total de cliques](https://www.notifuse.com/docs/assets/screenshots/broadcast_clicked_links.png)

### Integração com ferramentas de análise

- **Notifuse Web Analytics**: atribua as visitas trazidas por esses links, no seu próprio banco de dados. A regra embutida do canal Email usa os parâmetros acima. Veja [Web Analytics → Atribuição](https://www.notifuse.com/pt/docs/web-analytics/attribution.md).
- **Google Analytics**: acompanhe o desempenho dos emails no seu painel de análise.

Nos dois casos, você vê quais emails trazem tráfego e conversões para o site e mede o retorno sobre o investimento de cada campanha.

## Feeds de dados

Os feeds de dados buscam informações nas suas APIs para usar nos templates de email, para que o conteúdo vá além das propriedades de contato guardadas no Notifuse.

### Feed de dados global

O feed de dados global busca os dados uma única vez, antes do início do broadcast, e os deixa disponíveis para todos os destinatários.

#### Configuração

- **Ativação**: ative para ligar o feed de dados global
- **URL do feed**: o endpoint que retorna dados em JSON, por HTTPS ou HTTP
- **Cabeçalhos personalizados**: adicione cabeçalhos de autenticação ou outros (por exemplo, `Authorization: Bearer token123`)

#### Como funciona

1. Quando o broadcast começa, o Notifuse envia uma requisição POST para a URL configurada
2. O corpo da requisição traz informações do broadcast, da lista e do workspace:

```json
{
  "broadcast": {
    "id": "abc123",
    "name": "Summer Sale"
  },
  "list": {
    "id": "list456",
    "name": "Newsletter Subscribers"
  },
  "workspace": {
    "id": "ws789",
    "name": "My Company"
  }
}
```

3. Sua API deve retornar um objeto JSON com os dados que você quer usar
4. Os dados ficam em cache e disponíveis nos templates na variável `global_feed`

#### Uso nos templates

Acesse os dados do feed global nos seus templates pela variável `global_feed`:

```liquid
{% if global_feed.promotion %}
  <h2>{{ global_feed.promotion.title }}</h2>
  <p>{{ global_feed.promotion.description }}</p>
  <a href="{{ global_feed.promotion.url }}">Shop Now</a>
{% endif %}
```

#### Casos de uso

- **Promoções dinâmicas**: busque a promoção do momento, códigos de desconto ou produtos em destaque
- **Conteúdo em tempo real**: mostre estoque, preços ou disponibilidade atualizados
- **Dados centralizados**: traga conteúdo de um CMS ou de uma plataforma de marketing

### Feed de dados por destinatário

O feed de dados por destinatário busca dados personalizados para cada destinatário antes de enviar o email dele.

#### Configuração

- **Ativação**: ative para ligar o feed de dados por destinatário
- **URL do feed**: o endpoint que retorna dados em JSON, obrigatoriamente por HTTPS
- **Cabeçalhos personalizados**: adicione cabeçalhos de autenticação ou outros

#### Como funciona

1. Antes de enviar cada email, o Notifuse envia uma requisição POST para a URL configurada
2. O corpo da requisição traz informações do contato, do broadcast, da lista e do workspace:

```json
{
  "contact": {
    "email": "john@example.com",
    "external_id": "user_789",
    "timezone": "America/New_York",
    "language": "en",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "phone": "+1234567890",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "postcode": "10001",
    "state": "NY",
    "job_title": "Engineer",
    "custom_string_1": "value",
    "custom_number_1": 42,
    "custom_datetime_1": "2024-06-15T00:00:00Z",
    "custom_json_1": {"key": "value"},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-06-01T14:00:00Z"
  },
  "broadcast": {
    "id": "abc123",
    "name": "Summer Sale"
  },
  "list": {
    "id": "list456",
    "name": "Newsletter Subscribers"
  },
  "workspace": {
    "id": "ws789",
    "name": "My Company"
  }
}
```

Todos os campos do contato que têm valor são incluídos, e os vazios ficam de fora. O mesmo vale para os campos personalizados (de `custom_string_1` a `custom_string_5`, de `custom_number_1` a `custom_number_5`, de `custom_datetime_1` a `custom_datetime_5`, de `custom_json_1` a `custom_json_5`).

3. Sua API deve retornar um objeto JSON com os dados personalizados desse contato
4. Os dados ficam disponíveis nos templates na variável `recipient_feed`

#### Uso nos templates

Acesse os dados do feed por destinatário pela variável `recipient_feed`:

```liquid
{% if recipient_feed.recommendations %}
  <h3>Recommended for You</h3>
  {% for product in recipient_feed.recommendations %}
    <div>
      <img src="{{ product.image }}" alt="{{ product.name }}" />
      <p>{{ product.name }} - ${{ product.price }}</p>
    </div>
  {% endfor %}
{% endif %}
```

#### Casos de uso

- **Recomendações de produtos**: busque sugestões personalizadas com base no histórico de compras
- **Informações da conta**: mostre o status atual da assinatura, o saldo de pontos ou o nível de fidelidade
- **Conteúdo dinâmico**: mostre conteúdo conforme as preferências do usuário guardadas no seu sistema

### Tratamento de erros

#### Nova tentativa automática

Se uma requisição do feed por destinatário falhar, o Notifuse tenta de novo automaticamente:

- **Novas tentativas**: 2, ou seja, 3 tentativas no total
- **Intervalo entre tentativas**: 5 segundos

#### Quando todas as tentativas falham

- **O broadcast é pausado**: se o feed de um destinatário continuar falhando depois das novas tentativas, o broadcast pausa e mostra o motivo. Nenhum destinatário é pulado: um email nunca sai sem os dados do seu feed
- **Retomada manual**: depois de corrigir o problema, retome o broadcast pela interface

### Desempenho

#### Feed global

- **Uma única requisição**: só uma chamada de API por broadcast, seja qual for o tamanho da audiência
- **Dados em cache**: os dados são buscados uma vez e reutilizados para todos os destinatários
- **Recomendado**: use para dados que são iguais para todos os destinatários

#### Feed por destinatário

- **Uma requisição por destinatário**: uma chamada de API para cada destinatário da audiência
- **Impacto no processamento**: pode deixar o processamento do broadcast bem mais lento em audiências grandes
- **Limites de taxa da API**: confirme que a sua API aguenta o volume de requisições
- **Recomendado**: use só quando os dados precisam mesmo ser personalizados

#### Boas práticas

- **Respostas rápidas da API**: mantenha os endpoints dos feeds rápidos (menos de 2 segundos)
- **Infraestrutura confiável**: garanta alta disponibilidade para os endpoints dos feeds
- **Conteúdo alternativo**: um feed com falha nunca envia um email sem os dados. Se o feed global falhar, o broadcast não é agendado nem enviado e continua como rascunho; se um feed por destinatário falhar, o broadcast pausa. Um feed que responde ainda pode deixar um campo de fora, então verifique cada variável do feed com `if` antes de usá-la, como nos exemplos acima
- **Teste antes de enviar**: use o botão "Testar" para conferir as respostas do feed antes de lançar

### Segurança

As URLs dos feeds de dados são acessadas pelo servidor do Notifuse, por isso ficam protegidas contra [server-side request forgery (SSRF)](https://owasp.org/www-community/attacks/Server_Side_Request_Forgery):

- **Endereços privados são bloqueados**: por padrão, o servidor se recusa a se conectar a faixas de IP privadas, de loopback, link-local e outras reservadas, incluindo o endpoint de metadados da instância na nuvem. Isso vale tanto para um feed que aponta direto para um desses endereços quanto para um hostname que resolve para um deles, e os redirecionamentos são verificados de novo para impedir DNS rebinding.
- **Acesso de escrita obrigatório**: adicionar, testar ou atualizar um feed de dados exige a permissão de **Escrita** em `broadcasts`, o mesmo acesso necessário para criar um broadcast. Membros com acesso só de leitura não conseguem disparar requisições de feed.

> [!NOTE]
>
> **Auto-hospedagem:** se você serve feeds de dados de propósito a partir de serviços da sua rede interna, pode liberar endereços privados com `BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTS=true`. Isso desativa a proteção contra SSRF nas requisições de feed de dados, então ative apenas em ambientes confiáveis. Veja [Variáveis de ambiente](https://www.notifuse.com/pt/docs/self-hosting/installation.md#optional-variables).

## Permissões

Os broadcasts seguem a permissão **Broadcasts**. Com **Leitura**, o membro abre os broadcasts, a configuração deles e os resultados dos testes A/B. Com **Escrita**, ele cria e edita broadcasts, gerencia os feeds de dados e agenda, envia, pausa, retoma, devolve para rascunho, cancela e exclui broadcasts.

Dois pontos aqui costumam gerar confusão:

- **A escrita em Broadcasts permite enviar para toda a audiência.** A permissão que deixa alguém redigir uma campanha também deixa enviá-la; não existe uma permissão separada para enviar.
- **A leitura em Broadcasts não inclui as estatísticas de entrega.** Os números de entregas, aberturas, cliques, retornos e cliques por link vêm do log de mensagens, então exigem a permissão de leitura de **Histórico de Mensagens**. A lista de destinatários exige a leitura de **Contatos**. Um membro que tem só a leitura de Broadcasts vê a campanha, mas não os resultados.

Veja [Administradores e chaves API](https://www.notifuse.com/pt/docs/features/admins-api-keys.md).

## Criar um broadcast

**Novo broadcast** abre o editor: uma única tela com a audiência, o conteúdo, o momento do envio, o rastreamento web e as configurações avançadas, ao lado de uma pré-visualização ao vivo e de um resumo.

![O editor de broadcast: audiência, conteúdo, agendamento e configurações ao lado da pré-visualização e do resumo](https://www.notifuse.com/docs/assets/screenshots/edit_broadcast.png)

- **Salvo enquanto você digita**: o broadcast é criado como rascunho assim que tem um nome e uma lista, e cada alteração é salva um segundo depois que você para de digitar. A barra no topo mostra quando foi o último salvamento ou o que está faltando. Se você fechar com alterações ainda não salvas, o editor pede confirmação.
- **Audiencia**: escolha uma lista e, se quiser, segmentos. O número de destinatários é estimado na hora, a partir dos contatos ativos da lista e dos segmentos que você adiciona.
- **Conteúdo**: escolha um template para cada variante. O assunto, o texto de pré-visualização e o endereço de resposta vêm do template; o lápis abre o template para editá-los. Ative **Teste A/B** para adicionar variantes e definir a amostra do teste, a métrica do vencedor e a duração do teste.
- **Visualizar**: o email como vai aparecer no desktop ou no celular, para cada variante.
- **Resumo**: todas as verificações antes do envio, como lista ou template ausente, um remetente que não existe mais, um template sem link de cancelamento de inscrição ou a falta de um provedor de email de marketing. **Enviar agora** fica desativado até que os erros sejam corrigidos.
- **Enviar teste** envia o template escolhido para os endereços que você informar.

### Enviar agora ou depois

- **Agora**: **Enviar agora** pede confirmação mostrando o número de destinatários; depois o broadcast começa a ser enviado e os resultados abrem.
- **Agendar**: escolha data, horário e fuso horário (o do workspace, por padrão) e clique em **Agendar**. Um broadcast agendado pode ser editado até começar: altere-o e clique em **Salvar alterações**. Para retrabalhá-lo, **Voltar para rascunho**, disponível até o início do envio, transforma-o de novo em rascunho, que mantém a data e não é enviado até você agendá-lo outra vez. Depois que o envio começa, ele aparece como enviando: pause ou cancele pelos resultados.

### Boas práticas de agendamento

- Agende para o horário em que sua audiência está mais ativa.
- Leve em conta os fusos horários em que sua audiência vive.
- Evite feriados e os períodos de pico do seu setor.

## Resultados

![Os resultados de um broadcast enviado com teste A/B: funil, aberturas e cliques ao longo do tempo e os resultados de cada variante](https://www.notifuse.com/docs/assets/screenshots/broadcast_detail.png)

Um broadcast enviado abre nos resultados:

- **Funil**: enviados, entregues, abertos e clicados, com retornos, reclamações, cancelamentos de inscrição e falhas ao lado.
- **Aberturas e cliques ao longo do tempo**: primeiras aberturas e primeiros cliques em 48 horas, 7 dias ou 30 dias a partir do início do envio, com os momentos em que o teste A/B e o vencedor foram enviados.
- **Teste A/B**: cada variante com o template, o assunto, o remetente e os resultados, o vencedor depois de escolhido e **Escolher como vencedor** enquanto o teste espera por você.
- **Links clicados**: veja [Estatísticas por link](#per-link-statistics).
- **Ao lado**: a pré-visualização, a audiência, os parâmetros UTM, a tarefa de envio e o histórico do broadcast (criado, iniciado, teste e vencedor enviados, concluído, pausado).

O cabeçalho mostra o status e as ações que ele permite: editar um rascunho ou um broadcast agendado, enviar um teste, pausar, retomar, alterar o remetente, tentar de novo os destinatários com falha ou cancelar e, com web analytics, abrir o tráfego do site trazido pelo broadcast. O menu "…" atualiza as estatísticas, abre os logs de envio e as conversões no site, e exclui o broadcast.

## Velocidade de envio

Os broadcasts e os emails de automação saem pela fila de emails, na **Taxa de envio para marketing** definida no painel **Taxa de envio** de cada integração de email, em emails por minuto.

- **Defina o limite como o que o seu provedor aceita, menos o seu outro tráfego na mesma conta.** Os emails transacionais saem assim que a API é chamada e não contam nesse limite, mas, na mesma conta do provedor, usam a mesma cota. O mesmo vale para outras integrações nessa conta, neste workspace ou em outro: os limites delas se somam. O Amazon SES informa a cota por segundo: 100 emails por segundo são 6.000 por minuto.
- **O limite é um máximo e vale por instância do Notifuse.** Várias instâncias que compartilham um banco de dados aplicam o limite cada uma por conta própria, e cada uma desacelera por conta própria quando o provedor pede (veja abaixo). Enquanto é o limite que as segura, elas disputam os mesmos emails e, juntas, enviam mais ou menos no limite; quando ele está acima do que uma instância consegue alcançar (veja abaixo), as taxas se somam e podem passar dele. Abaixo do limite, o ritmo de uma instância depende dos pontos a seguir.
- **Emails enviados ao mesmo tempo.** Cada integração de email envia até 10 emails ao mesmo tempo, e as integrações SMTP, um de cada vez: cada email SMTP abre a própria conexão, e muitos servidores SMTP recusam várias ao mesmo tempo. Uma integração não vai mais rápido que esse número dividido pelo tempo de um email, que é a resposta do provedor mais cerca de três consultas no banco de dados do workspace: 10 ao mesmo tempo a 100 ms cada dá 6.000 por minuto, um de cada vez a 300 ms cada dá 200 por minuto. Uma instância auto-hospedada pode aumentar `EMAIL_QUEUE_CONCURRENCY`, ou `EMAIL_QUEUE_SMTP_CONCURRENCY` se o servidor SMTP aceitar várias conexões (veja [Instalação](https://www.notifuse.com/pt/docs/self-hosting/installation.md#optional-variables)). Isso ajuda quando a parte lenta é a resposta do provedor. Quando são as consultas ao banco (com um banco distante, por exemplo), o envio fica limitado pelas poucas conexões do workspace, compartilhadas com a API (`DB_MAX_CONNECTIONS_PER_DB`, 3 por padrão).
- **Rodadas.** Uma integração envia no máximo 200 emails por rodada, e uma rodada começa no máximo uma vez por segundo, então ela nunca passa de cerca de 12.000 por minuto por instância. Uma rodada termina quando todas as integrações da instância enviaram os emails dela. Enquanto outra integração envia tão rápido quanto o próprio limite permite, uma rodada leva cerca de dois segundos, ou menos quando esse limite passa de 6.000 por minuto. Isso baixa o teto para 6.000 por minuto, ou para o limite dessa integração quando ele fica entre 6.000 e 12.000. As rodadas demoram mais quando os emails de uma integração são lentos para sair.
- **Workspaces.** Uma instância envia para cinco workspaces por vez. Com mais de cinco enviando ao mesmo tempo, eles se revezam, e cada um fica abaixo do próprio limite.

### Quando o provedor pede para desacelerar

Com um limite acima do que o provedor aceita, ele responde que os emails estão chegando rápido demais. A integração então reduz o ritmo em um quarto a cada vez, até um décimo do limite (no mínimo um email por minuto), e, quando os emails voltam a passar, sobe de novo 5% do limite a cada 10 segundos, até chegar ao limite. O email recusado é enviado de novo no ritmo mais lento, mantém as tentativas de entrega, e o broadcast continua enviando. Até ser enviado, o email não aparece no Histórico de Mensagens, exceto os emails de automação do Mailgun, que mostram a recusa até lá. Mesmo assim, mantenha o limite igual ou abaixo do que o provedor aceita: cada vez que o ritmo sobe além disso, alguns emails são recusados.

- **O que conta como "rápido demais"**: um HTTP 429 do SendGrid, Mailgun, Mailjet, SparkPost ou Postmark, um erro de throttling do Amazon SES e uma recusa SMTP com código 4xx que diga isso (rate limit, too many messages, sending rate…), a menos que ela culpe a caixa de entrada do destinatário.
- **Cotas não são "rápido demais"**: uma recusa que cita uma cota diária, por hora ou mensal, ou créditos, é uma falha do provedor. As recusas do SendGrid, Mailgun, Mailjet e SparkPost trazem só o código de status, então uma cota respondida com 429 parece "rápido demais": a integração primeiro desacelera até um décimo do limite.
- **Quando desacelerar não basta**: recusas que continuam por 30 segundos a um décimo do limite também são falhas do provedor.

As outras recusas do provedor são falhas. Um email com falha é tentado de novo um minuto depois, depois mais dois minutos depois, e é abandonado na terceira recusa; tentar o broadcast de novo envia o email outra vez. Várias falhas seguidas pausam os broadcasts da integração (veja abaixo), e os outros emails na fila dela, como os de automação, esperam o fim do intervalo de espera. A integração então envia um deles como teste e, se ele passar, volta a enviar, subindo de novo até o limite se tiver desacelerado. Um broadcast com teste A/B em andamento também é pausado, seja qual for a etapa do teste. Com o Amazon SES, o cliente primeiro tenta de novo um email recusado durante vários segundos, o que segura a rodada para as outras integrações da instância.

## Tratamento de falhas de transmissão

### Proteção por circuit breaker

Depois de 5 falhas de transmissão seguidas, um circuit breaker pausa o broadcast; um provedor que pede para desacelerar não conta como falha (veja [Quando o provedor pede para desacelerar](#when-the-provider-asks-to-slow-down)). O status do broadcast passa para "Pausado", com um motivo dizendo que o circuit breaker foi acionado. Parar nesse ponto evita mais tentativas com falha e protege a reputação do remetente.

### Comportamento das mensagens com falha

Quando o circuit breaker é acionado:

- **Os destinatários são mantidos**: tudo o que ainda está na fila é pausado, não descartado, e mantém as tentativas de entrega restantes. Só as poucas mensagens de fato recusadas usaram uma tentativa; as que o provedor recusou de vez, ou na última tentativa, são abandonadas. Em uma única instância do Notifuse, um email que ainda está sendo enviado no momento do acionamento é pausado com os demais se o provedor o recusar, a menos que estivesse na última tentativa; um recusado por causa do destinatário é abandonado, como de costume.
- **Mensagens com falha**: esses destinatários aparecem como "failed" nos logs do Histórico de Mensagens, com a explicação do próprio provedor na coluna Erro.
- **Recuperável**: a pausa em si não faz perder nada. Retomar envia para os destinatários pausados, e os que foram abandonados podem ser tentados de novo à parte.

### Retomada manual obrigatória

Um broadcast pausado pelo circuit breaker precisa ser retomado manualmente pela interface, depois que você encontrar e corrigir o problema de entrega. Ele continua de onde parou. Os destinatários que esgotaram todas as tentativas não são retomados automaticamente: use **Tentar novamente os com falha** para eles.

### Tentar de novo os destinatários com falha

Um destinatário cujas tentativas de entrega foram todas recusadas fica guardado por **7 dias**, para que você possa enviar de novo para ele depois de corrigir a causa.

- **Onde**: um broadcast que terminou com falhas mostra "N com falha" em vez de "Enviado". **Tentar novamente os com falha** fica no cabeçalho dele e no menu "…" da linha dele na lista.
- **Quando**: só depois que o broadcast terminar o envio. Um broadcast que ainda está processando a fila, ou que está pausado, precisa terminar ou ser retomado antes.
- **O que acontece**: o mesmo email é enviado de novo para esses destinatários. Corrija o que o provedor rejeitou antes de tentar de novo, ou o envio vai falhar uma segunda vez.
- **Pela API**: `POST /api/broadcasts.retryFailed` com `workspace_id` e `id`, que responde com quantos destinatários voltaram para a fila.

> [!WARNING]
>
> Depois de 7 dias, os destinatários com falha são apagados e não podem mais ser tentados de novo a partir do broadcast.

### O que significa "concluído"

Um broadcast só aparece como concluído quando a fila está vazia e ninguém foi abandonado. O número **Enviado** conta as mensagens que o provedor de email aceitou; uma mensagem recusada entra em **Falhou**, nunca em Enviado.

### Cenários de falha comuns

O circuit breaker costuma disparar por causa de:

- **Problemas no provedor de email**: indisponibilidades temporárias, cota de envio atingida ou um provedor que continua recusando a um décimo do limite
- **Problemas de autenticação**: chaves API ou credenciais inválidas
- **Erros de configuração**: configurações SMTP ou do provedor incorretas
- **Problemas de reputação**: taxas de retorno altas ou reclamações de spam

### Etapas de recuperação

1. **Consulte os logs do Histórico de Mensagens** para identificar os motivos exatos das falhas
2. **Resolva o problema de origem** (corrija as credenciais, fale com o provedor etc.)
3. **Retome o broadcast** manualmente pela interface da campanha
4. **Acompanhe de perto** para confirmar que a entrega continua sem problemas

## Boas práticas

- **Segmentação de listas**: use filtros de segmento para atingir partes específicas da sua lista
- **Teste A/B**: teste assuntos e conteúdos para melhorar o engajamento
- **Consistência nos UTMs**: use nomes de campanha consistentes para análises mais claras
- **Feeds de dados**: use feeds globais para dados compartilhados e reserve os feeds por destinatário para conteúdo que precisa mesmo ser personalizado
- **Agende com estratégia**: envie quando a sua audiência estiver mais ativa
- **Acompanhe o desempenho**: analise as métricas para melhorar as próximas campanhas
- **Monitoramento do provedor**: fique de olho no status e nos limites do seu provedor de email
- **Campanhas de teste**: envie campanhas de teste para conferir a configuração antes de broadcasts grandes
