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

# Adicione um formulário de inscrição com confirmação dupla

> Coloque no seu site um formulário que adiciona inscritos a uma lista do Notifuse só depois que eles confirmam o endereço.

Ao final, você terá no seu site um formulário que inscreve os visitantes em uma lista do Notifuse, envia a eles um email de confirmação e os marca como ativos quando clicam no link.

## Antes de começar

- Um workspace com um provedor de email definido para **Emails de marketing** em Configurações › **Integrações**. Os emails de confirmação saem por esse provedor.
- O ID do seu workspace. É o ID que você escolheu ao criar o workspace, e ele aparece na URL do console depois de `/console/workspace/`.
- O endereço da sua instância do Notifuse, o mesmo em que você abre o console. Os exemplos usam `https://YOUR_NOTIFUSE_HOST`.
- Uma página do seu site em que você possa adicionar HTML e JavaScript.

### 1. Crie uma lista pública com confirmação dupla

Abra **Contatos** e clique em **Nova lista**, ao lado de **Listas**, na coluna da esquerda. Preencha:

- **Nome**: por exemplo, "Newsletter".
- **ID**: vem do nome, ou clique em **Modificar** para digitar o seu. Só letras e dígitos, com no máximo 32 caracteres. O seu formulário envia esse ID, e ele não pode mudar depois da criação.

Em **Assinatura**, ative as duas opções:

- **Lista pública**: o endpoint público `/subscribe` só aceita listas públicas.
- **Confirmação dupla**: os novos inscritos recebem um email de confirmação e ficam como **Pendente** até clicarem no link dele. Essa opção exige um **Modelo de confirmação**.

Em **Modelo de confirmação**, escolha um template da categoria **Opt-in**. Se você não tiver nenhum, clique em **Novo modelo** no seletor e parta do modelo pronto **Confirmação de inscrição**. Ele abre no editor de templates e volta já selecionado quando você o salva.

O email de confirmação precisa ter um link para `{{ confirm_subscription_url }}`. O modelo pronto já traz um botão que aponta para ele. No seu próprio template, escreva:

```html
<a href="{{ confirm_subscription_url }}">Confirm your subscription</a>
```

Clique em **Criar lista**.

![O painel Nova lista com Lista pública e Confirmação dupla ativadas e o modelo de confirmação a escolher](https://www.notifuse.com/docs/assets/screenshots/list_double_optin.png)

### 2. Adicione o formulário ao seu site

Esta página é um exemplo completo que já funciona. Substitua `YOUR_NOTIFUSE_HOST`, `YOUR_WORKSPACE_ID` e `YOUR_LIST_ID`, depois cole a página no seu site ou abra-a como arquivo para testar.

```html signup-form.html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Subscribe to our newsletter</title>
  <style>
    .signup { max-width: 420px; margin: 2rem auto; font-family: system-ui, sans-serif; }
    .signup label { display: block; margin: 0.75rem 0 0.25rem; font-size: 0.9rem; }
    .signup input { width: 100%; padding: 0.6rem; border: 1px solid #ccc; border-radius: 6px; box-sizing: border-box; }
    .signup button { margin-top: 1rem; width: 100%; padding: 0.7rem; border: 0; border-radius: 6px; background: #4f46e5; color: #fff; font-size: 1rem; cursor: pointer; }
    .signup button:disabled { opacity: 0.6; cursor: wait; }
    .signup .message { margin-top: 1rem; font-size: 0.9rem; }
    .signup .message.error { color: #b91c1c; }
    .signup .message.success { color: #15803d; }
  </style>
</head>
<body>
  <form class="signup" id="signup-form" novalidate>
    <h2>Subscribe to our newsletter</h2>

    <label for="first-name">First name (optional)</label>
    <input id="first-name" name="first_name" type="text" autocomplete="given-name" />

    <label for="email">Email</label>
    <input id="email" name="email" type="email" autocomplete="email" required />

    <button type="submit">Subscribe</button>
    <p class="message" id="signup-message" role="status" aria-live="polite"></p>
  </form>

  <script>
    const NOTIFUSE_HOST = 'https://YOUR_NOTIFUSE_HOST'
    const WORKSPACE_ID = 'YOUR_WORKSPACE_ID'
    const LIST_ID = 'YOUR_LIST_ID'

    const form = document.getElementById('signup-form')
    const button = form.querySelector('button')
    const message = document.getElementById('signup-message')

    function show(text, kind) {
      message.textContent = text
      message.className = 'message ' + kind
    }

    form.addEventListener('submit', async (event) => {
      event.preventDefault()

      const email = form.email.value.trim()
      const firstName = form.first_name.value.trim()

      if (!form.email.checkValidity() || email === '') {
        show('Please enter a valid email address.', 'error')
        return
      }

      const contact = { email }
      if (firstName) contact.first_name = firstName

      button.disabled = true
      show('Subscribing…', '')

      try {
        const response = await fetch(NOTIFUSE_HOST + '/subscribe', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            workspace_id: WORKSPACE_ID,
            contact,
            list_ids: [LIST_ID]
          })
        })

        if (response.ok) {
          form.reset()
          show('Almost done: check your inbox and click the link to confirm your subscription.', 'success')
        } else if (response.status === 429) {
          show('Too many attempts. Please try again in a few minutes.', 'error')
        } else {
          const result = await response.json().catch(() => ({}))
          show(result.error || 'Something went wrong. Please try again.', 'error')
        }
      } catch (error) {
        show('Network error. Please check your connection and try again.', 'error')
      } finally {
        button.disabled = false
      }
    })
  </script>
</body>
</html>
```

A mensagem de sucesso pede ao visitante que olhe a caixa de entrada: numa lista com confirmação dupla, ele só fica inscrito depois de clicar no link.

### 3. Como funciona a chamada de inscrição

Se você montar o formulário no seu próprio framework, esta é a chamada a reproduzir. `POST /subscribe` é público: não pede chave API, então pode ser chamado do navegador com segurança.

```json
{
  "workspace_id": "YOUR_WORKSPACE_ID",
  "contact": {
    "email": "visitor@example.com",
    "first_name": "Ada"
  },
  "list_ids": ["YOUR_LIST_ID"]
}
```

`workspace_id`, `contact` com um `email` válido e pelo menos um item em `list_ids` são obrigatórios. Os outros campos do contato, como `first_name` ou `last_name`, são opcionais.

As respostas:

| Status | Corpo                                                | Quando                                                                                                     |
| ------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `200`  | `{"success": true}`                                  | A solicitação foi aceita.                                                                                  |
| `400`  | `{"error": "list is not public"}`                    | Uma lista em `list_ids` não é pública.                                                                     |
| `400`  | `{"error": "invalid contact: invalid email format"}` | O email está malformado. Um campo ausente tem a sua própria mensagem, como `workspace_id is required`.     |
| `429`  | `{"error": "Too many subscription attempts. …"}`     | Um limite de taxa foi atingido. O cabeçalho `Retry-After` indica a espera em segundos.                     |
| `500`  | `{"error": "Failed to subscribe to lists"}`          | Qualquer outro caso, como um ID de lista desconhecido ou um email de confirmação que não pôde ser enviado. |

Algumas regras a mais:

- Os limites são de 10 solicitações por minuto para um mesmo endereço de email e de 50 por minuto a partir de um mesmo endereço IP.
- Endereços descartáveis são ignorados sem aviso. A resposta continua sendo `200`, e nenhum contato é criado.
- Uma solicitação anônima nunca sobrescreve os campos de um contato que já está no workspace.
- Um contato pendente que envia o formulário de novo recebe outra vez o email de confirmação. Um contato ativo continua ativo e não recebe nada.

Para o CORS, o Notifuse define `Access-Control-Allow-Origin` a partir da variável de ambiente `CORS_ALLOW_ORIGIN`, cujo padrão é `*`. Se você hospeda o Notifuse por conta própria e restringe essa variável, adicione a origem do seu site. A variável aceita uma lista separada por vírgulas.

### 4. Saiba o que acontece depois do envio

Numa lista com confirmação dupla, o Notifuse adiciona o visitante à lista como **Pendente** e envia o modelo de confirmação.

O link desse email abre a central de notificações, que confirma a inscrição. O contato passa de **Pendente** para **Ativo**, e o Notifuse registra um evento `list.confirmed`.

É sobre esse evento que você deve construir o resto. Uma automação com o gatilho **Lista** › **Confirmado** só alcança quem confirmou. Veja [Crie uma sequência de boas-vindas](https://www.notifuse.com/pt/docs/guides/welcome-sequence.md).

Os contatos que você adiciona pelo console ou com uma chave API não recebem o email de confirmação e vão direto para **Ativo**. A exceção é um contato que tinha cancelado a inscrição na lista: inscrevê-lo de novo pelo formulário, pelo console ou pela API o deixa outra vez como **Pendente** e envia o email de confirmação.

## Verifique se funciona

1. Envie o formulário com um endereço cuja caixa de entrada você consiga ler. O formulário deve mostrar a mensagem que pede para olhar a caixa de entrada.
2. Abra **Contatos**, encontre o seu endereço e abra o contato. No painel **Listas**, a lista aparece como **Pendente**.
3. Abra o email de confirmação e clique no link. A central de notificações abre e confirma a inscrição.
4. Abra o contato de novo: a lista agora aparece como **Ativo**. Na aba **Atividade**, o filtro **Listas e segmentos** mostra a mudança.

O email de confirmação também aparece em **Logs**, na aba **Mensagens**, com a origem **Outro**. Veja [Logs](https://www.notifuse.com/pt/docs/features/logs.md).

![Ficha de um contato: a lista Newsletter aparece como Pendente até o contato confirmar](https://www.notifuse.com/docs/assets/screenshots/contact_pending.png)

## Boas práticas

- Avise no formulário que você vai enviar um email de confirmação, e mantenha a mensagem de sucesso apontando para a caixa de entrada.
- Coloque um link para a sua política de privacidade ao lado do formulário.
- Mantenha o email de confirmação curto, com o link como botão principal. A versão em texto também deve conter `{{ confirm_subscription_url }}`.
- Mostre o campo `error` de uma resposta com falha, ou uma mensagem clara sua para cada status.
- Teste o formulário no celular e também no computador.

## Solução de problemas

- **`400` "list is not public"**: em **Contatos**, clique na lista na coluna da esquerda, depois em **Editar lista**, e ative **Lista pública**.
- **`400` "invalid contact: invalid email format"**: o endereço está malformado. Verifique o campo que o seu formulário envia como `contact.email`.
- **`429` "Too many subscription attempts"**: você atingiu o limite de 10 por email ou 50 por IP por minuto, o que acontece com facilidade durante os testes. Aguarde o tempo indicado em `Retry-After`.
- **`500` "Failed to subscribe to lists"**: confira o ID da lista em `list_ids` e se há um provedor de email definido para **Emails de marketing**, já que o email de confirmação é enviado durante a solicitação.
- **`200` mas nenhum email de confirmação**: procure um envio com falha em **Logs** › **Mensagens**. Um endereço descartável recebe `200` e nenhum email, e isso é intencional.
- **O navegador bloqueia a solicitação (CORS)**: verifique se `NOTIFUSE_HOST` está correto e acessível. Numa instância auto-hospedada, verifique se `CORS_ALLOW_ORIGIN` inclui a origem do seu site.
- **O contato continua Pendente**: ele ainda não clicou no link. Enviar o formulário de novo com o mesmo endereço reenvia o email de confirmação.

## Próximos passos

- [Crie uma sequência de boas-vindas](https://www.notifuse.com/pt/docs/guides/welcome-sequence.md) disparada por **Confirmado**.
- [Listas](https://www.notifuse.com/pt/docs/features/lists.md) explica as configurações de lista e os status de inscrição.
- [Central de notificações](https://www.notifuse.com/pt/docs/features/notification-center.md) é a página que os seus inscritos usam para confirmar e para gerenciar as inscrições.
