Guide pratique
URL d’inscription
Chaque liste de contacts dispose d’une URL d’inscription qui ajoute des personnes sans clé API. Découvrez le format de la requête, ce que le double opt-in y change, comment l’appeler en toute sécurité, ses limites et comment la réinitialiser.
Chaque liste de contacts dispose d’une URL d’inscription : un endpoint public qui ajoute une personne à la liste sans clé API. Utilisez-la pour relier à une liste un formulaire d’inscription de votre site, ou un outil no-code capable d’envoyer une requête JSON. Il s’agit d’un endpoint pour des requêtes POST, pas d’une page : l’ouvrir dans un navigateur n’inscrit personne.
POST https://api.emailit.com/subscribe/{token}Le token est propre à la liste et secret. Toute personne qui possède l’URL peut ajouter des adresses à la liste : traitez-la comme un mot de passe.
Trouver l’URL
-
Ouvrez la liste. Accédez à Email MarketingAudiences et sélectionnez la liste.
-
Copiez l’URL. Sélectionnez Subscribe URL et copiez l’URL depuis la boîte de dialogue. La boîte de dialogue affiche aussi un exemple de requête et indique si le double opt-in est activé.
Via l’API, Récupérer une liste renvoie la même valeur dans token.
Format de la requête
Envoyez une requête POST avec un corps JSON et Content-Type: application/json. Aucun en-tête Authorization n’est nécessaire.
emailstringobligatoirefirst_namestringlast_namestringcustom_fieldsobjectL’endpoint ne lit que du JSON. Les corps encodés comme un formulaire, qu’envoie un simple <form> HTML, sont rejetés avec 400 et « Invalid JSON in request body ».
Réponses
| Statut | Corps | Cas |
|---|---|---|
200 |
{ "message": "Subscribed successfully", "status": "subscribed" } |
Le double opt-in est désactivé, et la personne a été ajoutée, réinscrite ou était déjà abonnée. |
202 |
{ "message": "Check your inbox to confirm the subscription.", "status": "pending" } |
Le double opt-in est activé : l’e-mail de double opt-in a été envoyé et la personne rejoint la liste quand elle clique sur son lien. Les personnes déjà abonnées, ou qui s’inscrivent à nouveau juste après leur première inscription, reçoivent la même réponse, sans nouvel e-mail. |
400 |
{ "error": "Missing required field: email" } ou { "error": "Invalid email format" } |
L’adresse e-mail est absente ou mal formée, ou le corps n’est pas du JSON. |
403 |
{ "error": "Workspace suspended" } ou { "error": "Workspace scheduled for deletion" } |
L’espace de travail est suspendu ou sa suppression est programmée : il n’accepte donc aucune inscription. |
404 |
{ "error": "Audience not found" } |
Le jeton est erroné ou a été réinitialisé, ou la liste est archivée. |
422 |
{ "error": "...", "usage": { ... } } |
La liste a atteint sa limite d’abonnés. |
429 |
Plus de 30 requêtes en une minute depuis la même adresse IP ou, quand le double opt-in ou l’e-mail de confirmation est activé, trop d’inscriptions pour la liste ou depuis votre réseau au cours de la dernière heure. Réessayez après le nombre de secondes indiqué dans l’en-tête retry-after. |
|
503 |
{ "error": "The double opt-in email could not be sent. Please try again later.", "code": "..." } |
Le double opt-in est activé, mais l’e-mail de double opt-in n’a pas pu être envoyé, par exemple parce que le domaine d’envoi n’est pas vérifié ou que l’espace de travail n’a plus de crédits. La personne n’est pas ajoutée. |
Effet d’une inscription
- Nouvelle adresse : Emailit crée le contact et l’inscrit à la liste.
- Contact existant, absent de la liste : Emailit met à jour les noms et les champs personnalisés envoyés et inscrit le contact.
- Abonné existant qui s’était désinscrit : Emailit le réinscrit.
- Abonné existant toujours inscrit : rien ne change, et la réponse est quand même
200.
Avec le double opt-in activé, un nouveau contact est créé immédiatement, les noms et les champs personnalisés d’un contact existant ne sont pas modifiés, et l’inscription attend que la personne clique sur le lien de l’e-mail de double opt-in.
Une nouvelle inscription envoie des événements webhook subscriber.created (ou subscriber.updated pour une réinscription), démarre les automatisations Added to audience et envoie l’e-mail de confirmation de la liste s’il est activé. Les inscriptions n’envoient pas d’événements contact.* et ne modifient pas le statut marketing d’un contact : si le contact était désinscrit de toutes les listes, les campagnes continuent de l’ignorer jusqu’à ce que vous le réinscriviez depuis la liste Contacts.
Connecter un formulaire d’inscription
L’URL d’inscription n’a aucune protection contre les robots et n’accepte que du JSON. La configuration la plus sûre consiste à envoyer votre formulaire à votre propre serveur, à le contrôler sur place, puis à appeler l’URL d’inscription depuis le serveur. Le jeton reste ainsi absent du code source de votre page et vous pouvez bloquer le spam avant qu’il n’atteigne votre liste.
-
Ajoutez le formulaire à votre page. Envoyez-le vers un endpoint de votre propre site. Le champ masqué
websiteest un pot de miel (honeypot) : les personnes ne le voient pas, mais les robots le remplissent souvent.<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> -
Traitez le formulaire sur votre serveur. Écartez les envois qui ont rempli le pot de miel, vérifiez un CAPTCHA si vous en utilisez un, puis transmettez les champs à l’URL d’inscription au format JSON. Conservez le jeton dans une variable d’environnement comme
EMAILIT_SUBSCRIBE_TOKEN. Consultez les exemples côté serveur ci-dessous. -
Testez-le. Envoyez le formulaire avec votre propre adresse et vérifiez que vous apparaissez dans le tableau des abonnés de la liste.
Exemples côté serveur
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" }'Si votre page envoie le formulaire en JavaScript au lieu de recharger toute la page, appelez votre propre endpoint avec fetch et laissez l’appel à Emailit sur le serveur :
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 débit et volumes plus importants
L’URL d’inscription accepte 30 requêtes par minute depuis chaque adresse IP et renvoie 429 au-delà. Quand votre serveur transmet chaque inscription, elles proviennent toutes de l’IP de votre serveur : les 30 requêtes par minute s’appliquent donc à l’ensemble de votre site. Quand le double opt-in ou l’e-mail de confirmation est activé, les inscriptions sont aussi soumises à des limites d’usage raisonnable par liste et par réseau, car chacune envoie un e-mail. Si vous en attendez davantage, appelez plutôt Ajouter un abonné depuis votre serveur avec une clé API. Cet endpoint renvoie aussi 409 pour les personnes déjà abonnées et accepte "double_opt_in": true pour demander une confirmation.
Confirmer les inscriptions
Activez le double opt-in dans l’onglet Settings de la liste pour que chaque personne qui s’inscrit via l’URL d’inscription confirme d’abord son adresse. L’URL renvoie alors 202, Emailit envoie l’e-mail de double opt-in depuis votre domaine vérifié, et la personne rejoint la liste quand elle clique sur son lien. Votre formulaire peut afficher « Vérifiez votre boîte de réception » lorsqu’il reçoit 202.
Pour accueillir les personnes une fois inscrites, activez l’e-mail de confirmation de la liste.
Réinitialiser l’URL
Réinitialisez le jeton si l’URL a fuité ou si vous recevez des inscriptions indésirables. L’ancienne URL cesse immédiatement de fonctionner et renvoie 404.
-
Ouvrez la boîte de dialogue. Sur la page de la liste, sélectionnez Subscribe URL.
-
Réinitialisez. Sélectionnez Reset token et confirmez. Emailit génère une nouvelle URL.
-
Mettez à jour vos intégrations. Remplacez le jeton partout où vous l’utilisez, par exemple dans la variable
EMAILIT_SUBSCRIBE_TOKENde votre serveur.
La réinitialisation du jeton n’est possible que dans le tableau de bord.