URL d’inscription

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.

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

1. Ouvrez la liste. Accédez à Email Marketing›Audiences et sélectionnez la liste.

2. Copiez l’URL. Sélectionnez Subscribe URL et copiez l’URL depuis la boîte de dialogue.

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.

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

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, à part la date d’inscription, et la réponse est quand même 200.

Les inscriptions via l’URL d’inscription n’envoient pas d’événements webhook subscriber.* ou contact.* et ne démarrent pas les automatisations Added to audience. Elles ne modifient pas non plus 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.

1. Ajoutez le formulaire à votre page. Envoyez-le vers un endpoint de votre propre site. Le champ masqué website est un pot de miel (honeypot) : les personnes ne le voient pas, mais les robots le remplissent souvent.

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

3. 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 !== 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" }'

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. 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 démarre les automatisations Added to audience, par exemple pour envoyer un e-mail de bienvenue.

Confirmer les inscriptions

L’URL d’inscription ajoute les personnes immédiatement. Emailit n’envoie pas d’e-mail de confirmation et ne demande pas à la personne de confirmer son adresse (double opt-in).

Si vous voulez des inscriptions confirmées, intégrez la confirmation à votre propre parcours : quand quelqu’un envoie le formulaire, enregistrez la demande sur votre serveur et envoyez-lui un e-mail contenant un lien de confirmation qui renvoie vers votre site. N’appelez l’URL d’inscription qu’une fois ce lien ouvert.

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.

1. Ouvrez la boîte de dialogue. Sur la page de la liste, sélectionnez Subscribe URL.

2. Réinitialisez. Sélectionnez Reset token et confirmez. Emailit génère une nouvelle URL.

3. Mettez à jour vos intégrations. Remplacez le jeton partout où vous l’utilisez, par exemple dans la variable EMAILIT_SUBSCRIBE_TOKEN de votre serveur.

La réinitialisation du jeton n’est possible que dans le tableau de bord.

Voir aussi