Comment fonctionnent les formulaires

Un formulaire conserve deux copies de ce que voient les visiteurs. document est le brouillon que vous modifiez, et publishedDocument est ce qu'utilisent la page hébergée, l'intégration et le point de terminaison d'inscription. Enregistrer ne modifie que le brouillon, et POST /forms/{id}/publish le copie vers la version en ligne. hasUnpublishedChanges vous indique que les deux diffèrent.

• —draft : jamais publié. Personne ne peut le voir ni s'inscrire par son biais.
• —live : publié et accepte les inscriptions.
• —paused : publié mais fermé. La page affiche le message de fermeture tiré des textes du formulaire, et les inscriptions sont refusées.

Les settings sont à part : où vont les inscriptions, le double opt-in, l'expéditeur, ce qui se passe après l'inscription et qui est prévenu de chaque inscription. Ils s'appliquent dès qu'ils sont enregistrés, publiés ou non.

Un document se compose d'une liste de fields, des textes qui les entourent dans copy et d'un style. Chaque champ de saisie a une key, le nom sous lequel sa réponse est envoyée : une lettre minuscule suivie d'au plus 39 lettres minuscules, chiffres ou tirets bas, unique dans le formulaire et ne commençant jamais par oe_. Chaque formulaire a exactement un champ email, de clé email et obligatoire.

• —Champs de saisie : email, text, textarea, number, phone, url et date.
• —Choix : select, radio et checkboxes, chacun avec des options.
• —checkbox pour un oui ou un non, et consent pour une case qui doit être cochée quand elle est obligatoire.
• —audiences permet à la personne de choisir des listes : chaque value d'option est un id d'audience de cet espace de travail.
• —hidden porte une valeur que le visiteur ne voit jamais : celle que votre page envoie, ou à défaut sa defaultValue, comme un nom de campagne.
• —heading, paragraph et divider ne servent qu'à la mise en page du formulaire et n'envoient rien.

Définissez mapsTo sur firstName, lastName ou name dans un champ de texte, et la réponse devient le nom du contact que crée l'inscription. Un contact qui existe déjà garde son nom. Chaque réponse est conservée sur la soumission avec le libellé qu'elle avait, si bien que les anciennes soumissions se lisent toujours correctement après une modification du formulaire.

Publiez d'abord. Utilisez ensuite celle des trois méthodes qui convient à la page. Toutes atteignent le même formulaire et comptent les mêmes inscriptions. Les vues ne sont comptées que sur la page hébergée et l'intégration, si bien que les inscriptions passant par votre propre HTML ou code font monter le taux de conversion.

• —La page hébergée à l'adresse url, une page à part entière vers laquelle vous pouvez faire un lien depuis n'importe où.
• —Le script d'intégration, qui place le formulaire sur votre page dans un cadre qui se dimensionne tout seul.
• —Votre propre HTML ou code, qui envoie les réponses à subscribeUrl.

<script src="https://openemail.uk/embed/form.js" data-openemail-form="frm_3b9d2e7a1c4f80d56e2a9b14" async></script>

<form action="https://api.openemail.uk/subscribe/frm_3b9d2e7a1c4f80d56e2a9b14" method="post">  <input type="email" name="email" required>  <div style="position:absolute;left:-9999px" aria-hidden="true">    <input type="text" name="oe_website" tabindex="-1" autocomplete="off">  </div>  <button type="submit">Subscribe</button></form>

Un simple formulaire HTML est redirigé vers la page de remerciement, ou vers settings.redirectUrl. Du code qui envoie du JSON reçoit à la place une réponse JSON, décrite sur la page du point de terminaison d'inscription.

Quand settings.doubleOptIn est activé, une inscription est enregistrée comme pending et la personne reçoit par e-mail un lien envoyé depuis settings.senderAddress, une adresse de cet espace de travail. Elle rejoint les audiences quand elle l'ouvre. Le lien fonctionne pendant sept jours. Une personne qui s'est désabonnée d'une audience auparavant n'y est réabonnée que de cette façon, jamais par un formulaire en opt-in simple. S'inscrire de nouveau avant de confirmer met à jour l'inscription en attente au lieu d'en ajouter une autre.

Pour protéger les personnes à qui vous écrivez, une adresse reçoit au plus une confirmation par formulaire toutes les dix minutes, et cinq par jour sur l'ensemble de l'espace de travail. Vous pouvez approuver vous-même une inscription en attente, ou lui envoyer un nouveau lien.

• —La lecture nécessite forms:read et la modification forms:write. Approuver une inscription nécessite aussi contacts:write, car cela ajoute un contact.
• —Tout ce qui amène un formulaire à envoyer des e-mails nécessite aussi emails:send : activer le double opt-in, définir l'expéditeur ou l'e-mail de confirmation, publier ou reprendre un formulaire en double opt-in, et renvoyer une confirmation.
• —Une clé API et le propriétaire voient tous les formulaires de l'espace de travail. Une application connectée par un membre ne voit que les formulaires que ce membre a créés, et seulement les audiences que ce membre a créées ainsi que les audiences intégrées.
• —Créer, mettre à jour, publier, reprendre ou dupliquer un formulaire dont l'expéditeur ou les adresses à prévenir sortent de ce qu'une clé ou une application limitée peut atteindre donne un 422 capability_unsupported.
• —Une clé ou une application limitée à certaines adresses ne peut définir comme expéditeur et comme adresses à prévenir que des adresses qu'elle détient.
• —Supprimer un formulaire demande un code de vérification à une application OAuth, comme les autres changements destructifs. Une clé API n'en a jamais besoin.

Les webhooks form.submitted et form.confirmed informent vos systèmes de chaque inscription. Un webhook limité à certaines adresses ne les reçoit jamais, car les inscriptions appartiennent à tout l'espace de travail.

• —Un champ nommé oe_website est un piège à robots : laissez-le vide et hors de l'écran, comme le fait le HTML ci-dessus. Une inscription qui le remplit reçoit une réponse normale et est écartée.
• —La page hébergée et l'intégration vérifient aussi une heure de début signée, et un formulaire renvoyé plus vite qu'une personne ne pourrait le remplir est écarté de la même façon.
• —Un même réseau peut envoyer 40 inscriptions en dix minutes, tous formulaires confondus et quel qu'en soit le résultat. Au-delà, les appels en JSON reçoivent 429 form_rate_limited, et un simple formulaire HTML est redirigé vers la page hébergée avec ?outcome=limited.
• —Un espace de travail peut contenir 100 formulaires par défaut.

Tout ce qui est décrit ici existe aussi dans le SDK sous la forme openemail.forms et dans la CLI sous la forme openemail forms, et le serveur MCP dispose d'outils de formulaire, si bien qu'un agent peut créer, publier et suivre un formulaire. Via MCP, le client écrit lui-même le design et le passe comme document.

Envoyer des requêtes POST à subscribeUrl depuis votre propre code ne nécessite aucun identifiant. Envoyez les réponses en JSON, ajoutez la page où se trouvait le formulaire comme oe_source, omettez oe_started, et envoyez oe_website vide ou pas du tout. Toutes les inscriptions venant d'un même réseau partagent la limite de 40 toutes les dix minutes, si bien qu'un serveur qui relaie les inscriptions de nombreuses personnes l'atteint vite : ajoutez plutôt les personnes que vous connaissez déjà avec l'import dans une audience.