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

# Listas

> Listas são coleções de contatos no Notifuse. Use-as para agrupar o seu público e enviar campanhas de email direcionadas.

Exemplo:

```
- Newsletter Subscribers
- VIP Customers
- Event Attendees
- Product Updates
```

![Uma lista aberta na página Contatos](https://www.notifuse.com/docs/assets/screenshots/lists.png)

## Listas no console

As listas ficam na página **Contatos**, na coluna da esquerda, em **Listas**; não existe uma página separada de listas. O **+** ao lado de **Listas** (**Nova lista**) cria uma.

Ao selecionar uma lista, você vê:

- **As contagens de inscritos por status**: clique em uma para mostrar só esses contatos. As contagens de não inscritos, retornados e contatos com reclamação também mostram a parcela que representam na lista.
- **As configurações**: visibilidade, confirmação dupla e o template de confirmação, e o ID da lista. **Editar lista** abre o formulário.
- **Os membros**, com o status de cada um na lista e desde quando.

**Importar para a lista** importa um CSV direto para a lista, e o menu **…** a exclui.

## Status dos contatos

O status de um contato em uma lista define se ele pode receber emails:

| Status           | Entrega de emails         | Descrição                                         |
| ---------------- | ------------------------- | ------------------------------------------------- |
| **Ativo**        | ✅ Pode receber emails     | Inscritos confirmados, aptos a receber broadcasts |
| **Pendente**     | ❌ Não pode receber emails | Aguardando confirmação dupla                      |
| **Não Inscrito** | ❌ Não pode receber emails | Pediu para deixar de receber comunicações         |
| **Retornado**    | ❌ Nunca recebe emails     | O endereço de email é inválido ou inacessível     |
| **Reclamado**    | ❌ Nunca recebe emails     | Marcou emails como spam                           |

> **Importante**: os broadcasts deixam de fora os contatos não inscritos da lista, a menos que o broadcast defina `exclude_unsubscribed` como `false` (**Excluir destinatários que cancelaram a inscrição** desativado no console), por exemplo para um aviso de segurança ou um aviso legal. Os emails de um broadcast assim não trazem o cabeçalho `List-Unsubscribe`, então os clientes de email não mostram o botão de cancelar inscrição. Uma requisição à API sem `exclude_unsubscribed` exclui esses contatos, como o console faz. Contatos retornados e com reclamação nunca recebem emails, seja qual for a configuração.

Um contato que cancela a inscrição em um email enviado para uma lista em que ele não estava, como um email de automação, é registrado nessa lista como **não inscrito**. Um cancelamento de inscrição nunca substitui um status **retornado** ou **reclamado**.

## Visibilidade da lista

### Listas públicas

- **Central de notificações**: ✅ aparecem na central de notificações
- **Acesso dos inscritos**: os usuários podem ver essas listas e se inscrever nelas na sua central de notificações
- **Caso de uso**: newsletters, comunicados e comunicações gerais

### Listas privadas

- **Central de notificações**: ❌ não são oferecidas aos contatos que não estão nelas. Um contato vê uma lista privada em que está ativo ou pendente, e lá só pode sair dela.
- **Acesso dos inscritos**: só o workspace adiciona contatos, pelo console ou pela API autenticada (`lists.subscribe`). Um contato não pode entrar em uma lista privada pela central de notificações nem pelo endpoint público `/subscribe`, nem voltar depois de sair; só o workspace pode adicioná-lo de novo. Um link nos emails dele só permite confirmar uma inscrição pendente na confirmação dupla.
- **Caso de uso**: comunicações internas, segmentos VIP, listas transacionais ou broadcasts pontuais

## Configuração da confirmação dupla

### Ativar a confirmação dupla

Quando você ativa a confirmação dupla em uma lista:

- **Contatos importados**: os contatos adicionados por importação de CSV ou pela API ficam sempre **"ativo"** (eles não passam pela confirmação dupla)
- **Inscritos anônimos**: os usuários que se inscrevem por formulários (como o cadastro na newsletter do seu site) ficam **"pendente"**
- **Confirmação obrigatória**: os contatos pendentes precisam clicar em um link de confirmação no email para passar para o status "ativo"
- **Conformidade**: ajuda a cumprir o GDPR e reduz as reclamações de spam

**Exemplo**: um visitante preenche um formulário de newsletter no seu site e recebe um email de confirmação. Quando ele clica no link (que abre a central de notificações), o status muda de "pendente" para "ativo".

### Template de boas-vindas (opcional)

As listas não têm template de boas-vindas. O único email que uma lista envia por conta própria é o email de confirmação da inscrição, quando a confirmação dupla está ativada. Para dar boas-vindas aos novos inscritos, crie uma [automação](https://www.notifuse.com/pt/docs/features/automations.md) acionada por `list.subscribed` ou `list.confirmed` nessa lista.

### Template de cancelamento de inscrição (opcional)

As listas também não têm template de cancelamento de inscrição. Para enviar um email aos contatos que saem de uma lista, use uma automação acionada por `list.unsubscribed`.

## Reinscrições

Quando um contato tenta se inscrever em uma lista em que já esteve, o Notifuse age de acordo com o status atual dele:

| Status atual     | Comportamento                                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Ativo**        | Nada acontece. O contato já está inscrito. Retorna sucesso silenciosamente.                                                |
| **Pendente**     | O status não muda. Reenvia o email de confirmação (confirmação dupla).                                                     |
| **Não Inscrito** | Permitido. O status passa a **"pendente"** e um email de confirmação é enviado, mesmo que a lista use confirmação simples. |
| **Retornado**    | Bloqueado. O status não muda e nenhum email é enviado.                                                                     |
| **Reclamado**    | Bloqueado. O status não muda e nenhum email é enviado.                                                                     |

### Por que os contatos retornados e com reclamação são bloqueados

Enviar de novo para endereços que tiveram hard bounce ou que registraram reclamações de spam prejudica a reputação do remetente e pode colocar o seu domínio em listas de bloqueio. Esses contatos ficam suprimidos de forma permanente, tanto na aplicação quanto no banco de dados.

### Comportamento na importação em massa

Quando contatos são importados por CSV ou pela API com `subscribe_to_lists`, as mesmas proteções valem no banco de dados: o status **não inscrito**, **retornado** ou **reclamado** de um contato na lista não é sobrescrito, então uma operação em massa não consegue reativar por engano contatos que pediram para sair.

### Privacidade desde a concepção

O endpoint público `/subscribe` retorna HTTP 200 qualquer que seja o status do contato na lista, então um atacante não consegue sondá-lo para descobrir se um endereço de email está inscrito. Ele retorna 400 para uma requisição inválida ou uma lista que não é pública, 429 quando há tentativas demais do mesmo IP e 500 para outros erros.

## Permissões

As listas dependem da permissão **Listas**: **leitura** mostra as listas, as configurações e as contagens de inscritos, e **escrita** cria, edita e exclui listas e gerencia as inscrições. Listar os endereços dos membros de uma lista também exige leitura de **Contatos**, e alterar ou remover uma inscrição existente também exige escrita de **Contatos**.

No console, um membro com leitura de Listas, mas sem leitura de Contatos, ainda chega à página **Contatos**: a coluna da esquerda mostra as listas e as contagens, mas nenhum contato.

> [!WARNING]
>
> **Escrita de Listas é uma escrita de Contatos implícita.** Inscrever um endereço por `/api/lists.subscribe`
> cria ou sobrescreve o registro inteiro desse contato, com todos os campos presentes na requisição, sem
> precisar de escrita de Contatos. Assim, um membro ou uma chave API que só tem escrita de Listas ainda pode
> reescrever os dados dos seus contatos. Uma chamada autenticada também pode inscrever alguém em uma lista que
> não é pública. Conceda escrita de Listas só onde você concederia escrita de Contatos. Veja
> [Administradores e chaves API](https://www.notifuse.com/pt/docs/features/admins-api-keys.md).

## Boas práticas

1. Revise os status dos contatos com frequência para manter as suas listas saudáveis.
2. Ative a confirmação dupla para cumprir as regras e manter inscritos que realmente querem os seus emails.
3. Defina um template de confirmação nas listas com confirmação dupla e use automações para os emails de boas-vindas.
4. Use listas separadas para públicos diferentes (por exemplo, "Newsletter", "Atualizações do produto") e combine-as com filtros de segmento para direcionar os broadcasts.
