URL de inscrição

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.

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

1. Abra a lista. Acesse Email Marketing›Audiences e selecione a lista.

2. Copie a URL. Selecione Subscribe URL e copie a URL da caixa de diálogo.

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.

O 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

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, exceto a data de inscrição, e a resposta continua sendo 200.

As inscrições pela URL de inscrição não enviam eventos de webhook subscriber.* nem contact.* e não iniciam automações Added to audience. Elas também 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.

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

   signup.html

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

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

3. 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 !== 200) {
    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. 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 inicia automações Added to audience, por exemplo para enviar um e-mail de boas-vindas.

Confirmar inscrições

A URL de inscrição adiciona as pessoas imediatamente. O Emailit não envia um e-mail de confirmação nem pede que a pessoa confirme o endereço (double opt-in).

Se você quiser inscrições confirmadas, inclua a confirmação no seu próprio fluxo: quando alguém enviar o formulário, guarde a solicitação no seu servidor e envie à pessoa um e-mail com um link de confirmação que aponte de volta para o seu site. Chame a URL de inscrição apenas depois que ela abrir esse link.

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.

1. Abra a caixa de diálogo. Na página da lista, selecione Subscribe URL.

2. Redefina. Selecione Reset token e confirme. O Emailit gera uma nova URL.

3. Atualize as suas integrações. Substitua o token em todos os lugares em que você o usa, como a variável EMAILIT_SUBSCRIBE_TOKEN no seu servidor.

Só é possível redefinir o token pelo painel.

Veja também