Guida pratica
URL di iscrizione
Ogni lista ha un URL di iscrizione che aggiunge persone senza chiave API. Scopri il formato della richiesta, come cambia con il double opt-in, come chiamarlo in sicurezza, i suoi limiti e come reimpostarlo.
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. È un endpoint per richieste POST, non una pagina: aprirlo nel browser non iscrive nessuno.
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
-
Apri la lista. Vai a Email MarketingAudiences e seleziona la lista.
-
Copia l’URL. Seleziona Subscribe URL e copia l’URL dalla finestra. La finestra mostra anche una richiesta di esempio e se il double opt-in è attivo.
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.
emailstringobbligatoriofirst_namestringlast_namestringcustom_fieldsobjectL’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
| Stato | Corpo | Quando |
|---|---|---|
200 |
{ "message": "Subscribed successfully", "status": "subscribed" } |
Il double opt-in è disattivato, e la persona è stata aggiunta, reiscritta o era già iscritta. |
202 |
{ "message": "Check your inbox to confirm the subscription.", "status": "pending" } |
Il double opt-in è attivo: l’email di double opt-in è stata inviata e la persona entra nella lista quando fa clic sul suo link. Le persone già iscritte, o che si sono iscritte di nuovo subito dopo la prima volta, ricevono la stessa risposta senza una nuova email. |
400 |
{ "error": "Missing required field: email" } o { "error": "Invalid email format" } |
L’email manca o non è valida, oppure il corpo non è JSON. |
403 |
{ "error": "Workspace suspended" } o { "error": "Workspace scheduled for deletion" } |
Il workspace è sospeso o in attesa di eliminazione, quindi non accetta iscrizioni. |
404 |
{ "error": "Audience not found" } |
Il token è sbagliato o è stato reimpostato, oppure la lista è archiviata. |
422 |
{ "error": "...", "usage": { ... } } |
La lista ha raggiunto il limite di iscritti. |
429 |
Più di 30 richieste in un minuto dallo stesso indirizzo IP oppure, quando il double opt-in o l’email di conferma sono attivi, troppe iscrizioni per la lista o dalla tua rete nell’ultima ora. Riprova dopo il numero di secondi indicato nell’header retry-after. |
|
503 |
{ "error": "The double opt-in email could not be sent. Please try again later.", "code": "..." } |
Il double opt-in è attivo ma non è stato possibile inviare l’email di double opt-in, ad esempio perché il dominio di invio non è verificato o il workspace ha esaurito i crediti. La persona non viene aggiunta. |
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, e la risposta è comunque
200.
Con il double opt-in attivo, un nuovo contatto viene creato subito, nome, cognome e campi personalizzati di un contatto esistente non vengono modificati, e l’iscrizione resta in attesa finché la persona non fa clic sul link nell’email di double opt-in.
Una nuova iscrizione invia gli eventi webhook subscriber.created (o subscriber.updated per una reiscrizione), avvia le automazioni Added to audience e invia l’email di conferma della lista, se è attiva. Le iscrizioni non inviano eventi contact.* e non cambiano 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.
-
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.<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> -
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. -
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 >= 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 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. Quando il double opt-in o l’email di conferma sono attivi, le iscrizioni hanno anche limiti di uso corretto per lista e per rete, perché ognuna invia un’email. 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 accetta "double_opt_in": true per chiedere la conferma.
Conferma le iscrizioni
Attiva il double opt-in nella scheda Settings della lista perché chi si iscrive tramite l’URL di iscrizione debba prima confermare il proprio indirizzo. L’URL restituisce allora 202, Emailit invia l’email di double opt-in dal tuo dominio verificato e la persona entra nella lista quando fa clic sul suo link. Quando riceve 202, il tuo modulo può mostrare «Check your inbox».
Per dare il benvenuto alle persone una volta entrate nella lista, attiva l’email di conferma della lista.
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.
-
Apri la finestra. Nella pagina della lista, seleziona Subscribe URL.
-
Reimposta. Seleziona Reset token e conferma. Emailit genera un nuovo URL.
-
Aggiorna le integrazioni. Sostituisci il token ovunque lo usi, ad esempio nella variabile
EMAILIT_SUBSCRIBE_TOKENdel server.
Il token si può reimpostare solo dal pannello.