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.
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
/subscribesó 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 Adicione o formulário ao seu site
Esta página é um exemplo completo que já funciona. Substitua
YOUR_NOTIFUSE_HOST,YOUR_WORKSPACE_IDeYOUR_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.
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,contactcom umemailválido e pelo menos um item emlist_idssão obrigatórios. Os outros campos do contato, comofirst_nameoulast_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_idsnã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-Afterindica 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-Origina partir da variável de ambienteCORS_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.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
- 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.
- Abra Contatos, encontre o seu endereço e abra o contato. No painel Listas, a lista aparece como Pendente.
- Abra o email de confirmação e clique no link. A central de notificações abre e confirma a inscrição.
- 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.
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
errorde 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 comocontact.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 emRetry-After.500“Failed to subscribe to lists”: confira o ID da lista emlist_idse se há um provedor de email definido para Emails de marketing, já que o email de confirmação é enviado durante a solicitação.200mas nenhum email de confirmação: procure um envio com falha em Logs › Mensagens. Um endereço descartável recebe200e nenhum email, e isso é intencional.- O navegador bloqueia a solicitação (CORS): verifique se
NOTIFUSE_HOSTestá correto e acessível. Numa instância auto-hospedada, verifique seCORS_ALLOW_ORIGINinclui 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 disparada por Confirmado.
- Listas explica as configurações de lista e os status de inscrição.
- Central de notificações é a página que os seus inscritos usam para confirmar e para gerenciar as inscrições.
