Guia prático
URL de inscrição
Toda lista de contatos tem uma URL de inscrição que adiciona pessoas sem chave de API. Conheça o formato da requisição, o que muda com o double opt-in, como chamá-la com segurança, os limites dela e como redefini-la.
Cada lista de contatos tem uma URL de inscrição: um endpoint público que adiciona uma pessoa à lista sem chave de API. Use-a para conectar a uma lista um formulário de inscrição no seu site, ou uma ferramenta no-code que consiga enviar uma requisição JSON. Ela é um endpoint para requisições POST, não uma página: abri-la em um navegador não inscreve ninguém.
POST https://api.emailit.com/subscribe/{token}O token é um segredo da lista. Qualquer pessoa que tenha a URL pode adicionar endereços à lista, então trate-a como uma senha.
Encontrar a URL
-
Abra a lista. Acesse Email MarketingAudiences e selecione a lista.
-
Copie a URL. Selecione Subscribe URL e copie a URL da caixa de diálogo. A caixa de diálogo também mostra um exemplo de requisição e se o double opt-in está ativado.
Pela API, Obter uma lista de contatos retorna o mesmo valor em token.
Formato da requisição
Envie uma requisição POST com um corpo JSON e Content-Type: application/json. Nenhum cabeçalho Authorization é necessário.
emailstringobrigatóriofirst_namestringlast_namestringcustom_fieldsobjectO endpoint só lê JSON. Corpos codificados como formulário, que um <form> HTML simples envia, são rejeitados com 400 e “Invalid JSON in request body”.
Respostas
| Status | Corpo | Quando |
|---|---|---|
200 |
{ "message": "Subscribed successfully", "status": "subscribed" } |
O double opt-in está desativado, e a pessoa foi adicionada, reinscrita ou já estava inscrita. |
202 |
{ "message": "Check your inbox to confirm the subscription.", "status": "pending" } |
O double opt-in está ativado: o e-mail de double opt-in foi enviado, e a pessoa entra na lista quando clicar no link dele. Quem já está inscrito, ou se inscreveu de novo logo depois da primeira vez, recebe a mesma resposta sem um novo e-mail. |
400 |
{ "error": "Missing required field: email" } ou { "error": "Invalid email format" } |
O e-mail está ausente ou malformado, ou o corpo não é JSON. |
403 |
{ "error": "Workspace suspended" } ou { "error": "Workspace scheduled for deletion" } |
O workspace está suspenso ou com a exclusão agendada, então não aceita inscrições. |
404 |
{ "error": "Audience not found" } |
O token está errado ou foi redefinido, ou a lista está arquivada. |
422 |
{ "error": "...", "usage": { ... } } |
A lista atingiu o limite de inscritos. |
429 |
Mais de 30 requisições em um minuto a partir do mesmo endereço IP ou, quando o double opt-in ou o e-mail de confirmação estiver ativado, inscrições demais na lista ou a partir da sua rede na última hora. Tente de novo depois do número de segundos indicado no cabeçalho retry-after. |
|
503 |
{ "error": "The double opt-in email could not be sent. Please try again later.", "code": "..." } |
O double opt-in está ativado, mas não foi possível enviar o e-mail de double opt-in, por exemplo porque o domínio de envio não está verificado ou o workspace está sem créditos. A pessoa não é adicionada. |
O que uma inscrição faz
- Endereço novo: o Emailit cria o contato e o inscreve na lista.
- Contato existente, fora da lista: o Emailit atualiza o nome, o sobrenome e os campos personalizados que você enviou e inscreve o contato.
- Inscrito existente que tinha se descadastrado: o Emailit o inscreve de novo.
- Inscrito existente que está inscrito: nada muda, e a resposta continua sendo
200.
Com o double opt-in ativado, um contato novo é criado na hora, o nome, o sobrenome e os campos personalizados de um contato existente não são alterados, e a inscrição só acontece quando a pessoa clica no link do e-mail de double opt-in.
Uma nova inscrição envia eventos de webhook subscriber.created (ou subscriber.updated, no caso de uma reinscrição), inicia automações Added to audience e envia o e-mail de confirmação da lista quando ele está ativado. As inscrições não enviam eventos contact.* e não alteram o status de marketing de um contato: se o contato estava descadastrado globalmente, as campanhas continuam a ignorá-lo até você reinscrevê-lo na página de contatos.
Conectar um formulário de inscrição
A URL de inscrição não tem proteção contra bots e só aceita JSON. A configuração mais segura é enviar o formulário para o seu próprio servidor, verificá-lo lá e chamar a URL de inscrição a partir do servidor. Isso mantém o token fora do código-fonte da sua página e permite bloquear spam antes que ele chegue à sua lista.
-
Adicione o formulário à sua página. Envie-o para um endpoint no seu próprio site. O campo oculto
websiteé um honeypot: as pessoas não o veem, mas os bots costumam preenchê-lo.<form id="signup" method="post" action="/newsletter"> <label for="email">Email</label> <input id="email" name="email" type="email" required> <label for="first_name">First name</label> <input id="first_name" name="first_name" type="text"> <!-- Honeypot: hidden from people, often filled in by bots --> <div style="position:absolute;left:-10000px" aria-hidden="true"> <input name="website" type="text" tabindex="-1" autocomplete="off"> </div> <button type="submit">Subscribe</button> <p class="status" role="status"></p> </form> -
Trate o formulário no seu servidor. Descarte os envios que preencheram o honeypot, verifique um CAPTCHA se você usar um e encaminhe os campos à URL de inscrição como JSON. Guarde o token em uma variável de ambiente como
EMAILIT_SUBSCRIBE_TOKEN. Consulte os exemplos de servidor abaixo. -
Teste. Envie o formulário com o seu próprio endereço e confira se você aparece na tabela de inscritos da lista.
Exemplos de servidor
import express from 'express';
const app = express();
app.post('/newsletter', express.urlencoded({ extended: false }), async (req, res) => {
// Bots fill in the honeypot. Pretend it worked and stop.
if (req.body.website) return res.redirect(303, '/thanks');
const response = await fetch(
`https://api.emailit.com/subscribe/${process.env.EMAILIT_SUBSCRIBE_TOKEN}`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: req.body.email,
first_name: req.body.first_name || undefined,
}),
},
);
if (!response.ok) {
const { error } = await response.json().catch(() => ({}));
return res.status(response.status).send(error || 'Could not subscribe.');
}
res.redirect(303, '/thanks');
});
app.listen(3000);<?php
// Bots fill in the honeypot. Pretend it worked and stop.
if (!empty($_POST['website'])) {
header('Location: /thanks', true, 303);
exit;
}
$token = getenv('EMAILIT_SUBSCRIBE_TOKEN');
$ch = curl_init("https://api.emailit.com/subscribe/{$token}");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'email' => $_POST['email'] ?? '',
'first_name' => $_POST['first_name'] ?? null,
]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 300) {
http_response_code($status);
echo json_decode($body, true)['error'] ?? 'Could not subscribe.';
exit;
}
header('Location: /thanks', true, 303);curl "https://api.emailit.com/subscribe/$EMAILIT_SUBSCRIBE_TOKEN" \
-X POST \
-H "Content-Type: application/json" \
-d '{ "email": "ada@example.com", "first_name": "Ada" }'Se a sua página envia o formulário com JavaScript em vez de recarregar a página inteira, chame o seu próprio endpoint com fetch e mantenha a chamada ao Emailit no servidor:
document.querySelector('#signup').addEventListener('submit', async (event) => {
event.preventDefault();
const form = new FormData(event.target);
const response = await fetch('/newsletter', { method: 'POST', body: new URLSearchParams(form) });
event.target.querySelector('.status').textContent = response.ok
? 'Thanks, you are subscribed.'
: 'Something went wrong. Please try again.';
});Limite de requisições e volumes maiores
A URL de inscrição aceita 30 requisições por minuto de cada endereço IP e retorna 429 acima disso. Quando o seu servidor encaminha todas as inscrições, elas vêm todas do IP do seu servidor, então as 30 por minuto valem para o seu site inteiro. Quando o double opt-in ou o e-mail de confirmação estiver ativado, as inscrições também têm limites de uso justo por lista e por rede, porque cada uma envia um e-mail. Se você espera mais, chame Adicionar um inscrito a partir do seu servidor com uma chave de API. Esse endpoint também retorna 409 para pessoas que já estão inscritas e aceita "double_opt_in": true para pedir confirmação.
Confirmar inscrições
Ative o double opt-in na aba Settings da lista para que todas as inscrições pela URL de inscrição confirmem o endereço primeiro. A URL passa então a retornar 202, o Emailit envia o e-mail de double opt-in a partir do seu domínio verificado, e a pessoa entra na lista quando clica no link dele. O seu formulário pode mostrar “Confira a sua caixa de entrada” quando receber 202.
Para dar as boas-vindas às pessoas assim que elas entrarem na lista, ative o e-mail de confirmação da lista.
Redefinir a URL
Redefina o token se a URL vazou ou se você estiver recebendo inscrições de spam. A URL antiga para de funcionar imediatamente e retorna 404.
-
Abra a caixa de diálogo. Na página da lista, selecione Subscribe URL.
-
Redefina. Selecione Reset token e confirme. O Emailit gera uma nova URL.
-
Atualize as suas integrações. Substitua o token em todos os lugares em que você o usa, como a variável
EMAILIT_SUBSCRIBE_TOKENno seu servidor.
Só é possível redefinir o token pelo painel.