Formulaires
`forms.list`, `get`, `create`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `listStarters`, `getStarter`, `listSubmissions`, `getSubmission`, `deleteSubmission`, `deleteSubmissions`, `approveSubmission`, `resendConfirmation` et `subscribe`.
Toutes les méthodes
const form = await openemail.forms.create({ name: 'Newsletter sign-up', starter: 'newsletter', settings: { audienceIds: ['aud_4c1b8e2a7d9f05c36b4e8a71'] }, publish: true,}) console.log(form.url, form.subscribeUrl) const saved = await openemail.forms.update(form.id, { settings: { doubleOptIn: true, senderAddress: '[email protected]' }, expectedUpdatedAt: form.updatedAt,}) const signup = await openemail.forms.subscribe(form.id, { email: '[email protected]', first_name: 'Ann', consent: true,}) for await (const submission of openemail.forms.iterateSubmissions(form.id, { status: 'pending' })) { if (submission.expired) await openemail.forms.resendConfirmation(form.id, submission.id)} const stats = await openemail.forms.analytics(form.id, { days: 30 })const starters = await openemail.forms.listStarters() await openemail.forms.pause(form.id)await openemail.forms.resume(form.id)const copy = await openemail.forms.duplicate(form.id)await openemail.forms.delete(copy.id) console.log(saved.senderIssue, signup.outcome, stats.totals.conversion, starters.length)Un formulaire conserve un brouillon document et le publishedDocument que voient les visiteurs. update modifie le brouillon et les paramètres, et publish met le brouillon en ligne. Les paramètres prennent effet immédiatement, publiés ou non, et expectedUpdatedAt refuse avec un 409 version_conflict un enregistrement qui écraserait celui de quelqu'un d'autre.
La lecture nécessite forms:read et la modification forms:write. approveSubmission nécessite aussi contacts:write, car cela ajoute un contact. resendConfirmation nécessite aussi emails:send, tout comme un appel qui amène le formulaire à envoyer des e-mails : activer doubleOptIn, définir senderAddress ou l'e-mail de confirmation, ou publier ou reprendre un formulaire en double opt-in. delete demande un code de vérification à un jeton d'accès OAuth, jamais à une clé API.
subscribe inscrit quelqu'un comme le fait la page du formulaire et n'envoie aucun identifiant, même depuis un client qui en détient un. Toutes les inscriptions venant d'un même réseau partagent une 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 audiences.importContacts. Passez la page où se trouvait le formulaire comme oe_source, omettez oe_started, et envoyez oe_website vide ou pas du tout.
Un 422 de subscribe est un invalid_form_submission, et le fields de l'erreur liste chaque réponse manquante ou non valide sous la forme { key, error }, avec des raisons comme required, email et option. Le client est fait pour les serveurs. Dans un navigateur, envoyez les réponses avec fetch au subscribeUrl du formulaire, sous forme de corps JSON ou avec un en-tête Accept: application/json, et il répond en JSON quelle que soit l'origine. Sans l'un ni l'autre, il répond par une redirection 303 vers la page hébergée.
Réponse : FormDetailResource
list se résout en une page de FormResource, du plus récent au plus ancien, sans document ni settings, et listAll et iterate parcourent toutes les pages. get, create, update, publish, pause, resume et duplicate se résolvent en un FormDetailResource, qui ajoute document, publishedDocument, settings, audiences, senderIssue et senderProblem.
idstring- La référence durable, `frm_` suivi de 24 caractères hexadécimaux.
status'draft' | 'live' | 'paused'- `draft` jusqu'à la première publication, puis `live` tant qu'il accepte les inscriptions et `paused` tant qu'il ne les accepte pas. Un formulaire ne revient jamais à `draft`.
urlstring- La page hébergée du formulaire publié, à partager sous forme de lien.
subscribeUrlstring- L'adresse où un simple formulaire HTML, ou `fetch`, envoie les réponses.
documentFormDocument- Le brouillon : les `fields` dans l'ordre, les textes de `copy` qui les entourent et le `style`.
publishedDocumentFormDocument | null- Ce que voient les visiteurs maintenant. Null jusqu'à la première publication.
settingsFormSettings- Où vont les inscriptions et ce qui se passe après chacune : `audienceIds`, `doubleOptIn`, `senderAddress`, l'e-mail de confirmation, `successAction`, `redirectUrl` et `notifyAddresses`.
hasUnpublishedChangesboolean- True quand le brouillon diffère de ce que voient les visiteurs. Toujours false avant la première publication.
senderIssue'missing' | 'not_sendable' | 'not_allowed' | null- Pourquoi un formulaire en double opt-in ne peut pas envoyer ses e-mails de confirmation en ce moment, ou null quand il le peut.
statsFormStats- `views`, `submissions`, `added`, `pending` et `lastSubmittedAt`, comptés au moment de la lecture.
Soumissions
listSubmissions renvoie des pages de la plus récente à la plus ancienne, avec q pour chercher dans les adresses e-mail et status pour pending ou added, et listAllSubmissions et iterateSubmissions parcourent toutes les pages. Chaque FormSubmissionResource conserve les réponses telles qu'elles ont été envoyées, libellés compris, si bien qu'elle se lit toujours correctement après une modification du formulaire.
resendConfirmation se résout en la soumission avec confirmationSent. Il vaut false quand rien n'est parti : une adresse reçoit une confirmation par formulaire toutes les dix minutes et cinq par jour sur l'ensemble de l'espace de travail, et une soumission déjà ajoutée n'en reçoit aucune. expired marque une inscription en attente dont le dernier lien a expiré.
