Pular para o conteúdo

Aumente seu público

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:

    <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
    O painel Nova lista com Lista pública e Confirmação dupla ativadas e o modelo de confirmação a escolher
  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.

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

    {
      "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:

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

    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.

Ficha de um contato: a lista Newsletter aparece como Pendente até o contato confirmar
Ficha de um contato: a lista Newsletter aparece como Pendente até o contato confirmar

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