Formulaires
`forms.list`, `get`, `create`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `list_starters`, `get_starter`, `list_submissions`, `get_submission`, `delete_submission`, `delete_submissions`, `approve_submission`, `resend_confirmation` et `subscribe`.
Toutes les méthodes
form = client.forms.create( name: "Newsletter sign-up", starter: "newsletter", settings: {audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"]}, publish: true) puts form[:url], form[:subscribeUrl] saved = client.forms.update( form[:id], settings: {doubleOptIn: true, senderAddress: "[email protected]"}, expectedUpdatedAt: form[:updatedAt]) signup = client.forms.subscribe(form[:id], email: "[email protected]", first_name: "Ann", consent: true) client.forms.iterate_submissions(form[:id], status: "pending") do |submission| client.forms.resend_confirmation(form[:id], submission[:id]) if submission[:expired]end stats = client.forms.analytics(form[:id], days: 30)starters = client.forms.list_starters client.forms.pause(form[:id])client.forms.resume(form[:id])copy = client.forms.duplicate(form[:id])client.forms.delete(copy[:id]) puts saved[:senderIssue], signup[:outcome], stats.dig(:totals, :conversion), starters.sizeUn formulaire garde 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 un enregistrement qui écraserait celui de quelqu'un d'autre avec un 409 version_conflict, levé sous forme d'OpenEmail::ConflictError.
Les champs d'un formulaire gardent les noms en camelCase de l'API (expectedUpdatedAt:, doubleOptIn), passés en arguments nommés ou en un seul Hash, alors que les filtres et les options sont des mots-clés en snake_case (status: sur list_submissions, offset_minutes: sur analytics). Un formulaire revient sous forme de Hash à clés Symbol : form[:subscribeUrl] lit donc l'adresse qui reçoit les inscriptions.
La lecture exige forms:read et la modification forms:write. approve_submission exige aussi contacts:write, car il ajoute un contact. resend_confirmation exige aussi emails:send, tout comme un appel qui fait envoyer du courrier au formulaire : activer doubleOptIn, définir senderAddress ou l'e-mail de confirmation, ou publier ou reprendre un formulaire à double opt-in. delete demande un code de vérification à un jeton d'accès OAuth, et jamais à une clé API. Tant que le jeton n'en a pas, delete lève OpenEmail::PermissionError avec step_up_required? à true.
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 : api_key: est donc ignoré. Les réponses se passent en arguments nommés ou en un seul Hash, avec pour clés les clés des champs du formulaire. Toutes les inscriptions venant d'un même réseau partagent une limite de 40 toutes les dix minutes : un serveur qui relaie des inscriptions pour de nombreuses personnes l'atteint donc vite. Ajoutez plutôt les personnes que vous connaissez déjà avec audiences.import_contacts. Au-delà de la limite, l'appel lève OpenEmail::RateLimitError. 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 invalid_form_submission, levé sous forme d'OpenEmail::ValidationError, et les fields de l'erreur listent chaque réponse manquante ou invalide sous forme de Hash avec key et error, avec des raisons comme required, email et option. OpenEmail::FORM_FIELD_ERRORS nomme chaque raison. La gem s'exécute sur un serveur. Un navigateur envoie lui-même les réponses à la subscribeUrl du formulaire, en corps JSON ou avec un en-tête Accept: application/json, et reçoit du JSON quelle que soit l'origine. Sans l'un ni l'autre, il reçoit une redirection 303 vers la page hébergée.
Réponse : un formulaire
list renvoie une OpenEmail::Page de formulaires, du plus récent au plus ancien, sans document ni settings, et list_all et iterate parcourent toutes les pages. get, create, update, publish, pause, resume et duplicate renvoient le formulaire complet sous forme de Hash, qui ajoute document, publishedDocument, settings, audiences, senderIssue et senderProblem.
idString- La référence durable, `frm_` suivi de 24 caractères hexadécimaux.
statusString- `draft` jusqu'à la première publication, puis `live` tant qu'il accepte des inscriptions et `paused` tant qu'il n'en accepte pas. Un formulaire ne revient jamais à `draft`. `OpenEmail::FORM_STATUSES` nomme les trois.
urlString- La page hébergée du formulaire publié, à partager sous forme de lien.
subscribeUrlString- L'adresse à laquelle un simple formulaire HTML, ou un script dans le navigateur, envoie les réponses.
documentHash- Le brouillon : les `fields` dans l'ordre, les textes de `copy` qui les entourent et le `style`.
publishedDocumentHash or nil- Ce que voient les visiteurs actuellement, ou nil jusqu'à la première publication.
settingsHash- 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.
senderIssueString or nil- Pourquoi un formulaire à double opt-in ne peut pas envoyer ses e-mails de confirmation pour le moment : `missing`, `not_sendable` ou `not_allowed`. nil quand il le peut. `OpenEmail::FORM_SENDER_ISSUES` nomme les trois.
statsHash- `views`, `submissions`, `added`, `pending` et `lastSubmittedAt`, comptés au moment de la lecture.
Soumissions
list_submissions pagine du plus récent au plus ancien, avec q: pour chercher dans les adresses e-mail et status: pour pending ou added, et list_all_submissions et iterate_submissions parcourent toutes les pages. OpenEmail::FORM_SUBMISSION_STATUSES nomme les deux statuts. Chaque soumission est un Hash qui garde les réponses telles qu'elles ont été envoyées, libellés compris, pour qu'elle reste lisible après une modification du formulaire.
resend_confirmation renvoie 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 ajoutée n'en reçoit aucune. expired marque une inscription en attente dont le dernier lien a expiré.