URL di iscrizione

Ogni lista ha un URL di iscrizione: un endpoint pubblico che aggiunge una persona alla lista senza chiave API. Usalo per collegare a una lista un modulo di iscrizione del tuo sito, o uno strumento no-code in grado di inviare una richiesta JSON.

POST https://api.emailit.com/subscribe/{token}

Il token è un segreto della lista. Chiunque abbia l’URL può aggiungere indirizzi alla lista, quindi trattalo come una password.

Trova l’URL

1. Apri la lista. Vai a Email Marketing›Audiences e seleziona la lista.

2. Copia l’URL. Seleziona Subscribe URL e copia l’URL dalla finestra.

Con l’API, Recupera una lista restituisce lo stesso valore in token.

Formato della richiesta

Invia una richiesta POST con un corpo JSON e Content-Type: application/json. Non serve l’header Authorization.

L’endpoint legge solo JSON. I corpi codificati come modulo, quelli che invia un semplice <form> HTML, vengono rifiutati con 400 e «Invalid JSON in request body».

Risposte

Cosa fa un’iscrizione

• Indirizzo nuovo: Emailit crea il contatto e lo iscrive alla lista.
• Contatto esistente, non nella lista: Emailit aggiorna nome, cognome e campi personalizzati inviati e iscrive il contatto.
• Iscritto esistente che si era disiscritto: Emailit lo iscrive di nuovo.
• Iscritto esistente e iscritto: non cambia nulla tranne la data di iscrizione, e la risposta è comunque 200.

Le iscrizioni tramite l’URL di iscrizione non inviano eventi webhook subscriber.* o contact.* e non avviano le automazioni Added to audience. Non cambiano nemmeno lo stato marketing di un contatto: se il contatto era disiscritto a livello globale, le campagne continuano a saltarlo finché non lo reiscrivi dall’elenco dei contatti.

Collega un modulo di iscrizione

L’URL di iscrizione non ha protezione dai bot e accetta solo JSON. La configurazione più sicura è inviare il modulo al tuo server, controllarlo lì e chiamare l’URL di iscrizione dal server. Così il token resta fuori dal codice sorgente della pagina e puoi bloccare lo spam prima che arrivi alla lista.

1. Aggiungi il modulo alla pagina. Invialo a un endpoint del tuo sito. Il campo nascosto website è un honeypot: le persone non lo vedono, ma i bot spesso lo compilano.

   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. Gestisci il modulo sul server. Scarta gli invii che compilano l’honeypot, controlla un CAPTCHA se ne usi uno, poi inoltra i campi all’URL di iscrizione come JSON. Tieni il token in una variabile d’ambiente come EMAILIT_SUBSCRIBE_TOKEN. Vedi gli esempi lato server qui sotto.

3. Provalo. Invia il modulo con il tuo indirizzo e controlla di comparire nella tabella degli iscritti della lista.

Esempi lato server

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 la pagina invia il modulo con JavaScript invece di ricaricarsi per intero, chiama il tuo endpoint con fetch e tieni la chiamata a Emailit sul server:

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 di frequenza e volumi più alti

L’URL di iscrizione accetta 30 richieste al minuto da ciascun indirizzo IP e oltre restituisce 429. Se il server inoltra ogni iscrizione, provengono tutte dall’IP del server, quindi il limite di 30 al minuto vale per l’intero sito. Se prevedi volumi maggiori, chiama invece Aggiungi un iscritto dal server con una chiave API. Quell’endpoint restituisce anche 409 per le persone già iscritte e avvia le automazioni Added to audience, ad esempio per inviare un’email di benvenuto.

Conferma le iscrizioni

L’URL di iscrizione aggiunge le persone subito. Emailit non invia un’email di conferma e non chiede alla persona di confermare il proprio indirizzo (double opt-in).

Se vuoi iscrizioni confermate, integra la conferma nel tuo flusso: quando qualcuno invia il modulo, memorizza la richiesta sul server e inviagli un’email con un link di conferma che rimanda al tuo sito. Chiama l’URL di iscrizione solo dopo che la persona ha aperto quel link.

Reimposta l’URL

Reimposta il token se l’URL è trapelato o se ricevi iscrizioni di spam. Il vecchio URL smette subito di funzionare e restituisce 404.

1. Apri la finestra. Nella pagina della lista, seleziona Subscribe URL.

2. Reimposta. Seleziona Reset token e conferma. Emailit genera un nuovo URL.

3. Aggiorna le integrazioni. Sostituisci il token ovunque lo usi, ad esempio nella variabile EMAILIT_SUBSCRIBE_TOKEN del server.

Il token si può reimpostare solo dal pannello.

Vedi anche