Formulaires
`forms->list`, `listAll`, `iterate`, `get`, `create`, `design`, `redesign`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `listStarters`, `getStarter`, `listSubmissions`, `getSubmission`, `deleteSubmission`, `deleteSubmissions`, `approveSubmission`, `resendConfirmation` et `subscribe`.
Toutes les méthodes
use OpenEmail\Constants\FormStarterSlugs;use OpenEmail\Constants\FormSubmissionStatuses; $form = $client->forms->create([ 'name' => 'Newsletter sign-up', 'starter' => FormStarterSlugs::NEWSLETTER, 'settings' => ['audienceIds' => ['aud_4c1b8e2a7d9f05c36b4e8a71']], 'publish' => true,]); echo $form['url'], ' ', $form['subscribeUrl'], PHP_EOL; $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,]); foreach ($client->forms->iterateSubmissions($form['id'], status: FormSubmissionStatuses::PENDING) as $submission) { if ($submission['expired']) { $client->forms->resendConfirmation($form['id'], $submission['id']); }} $stats = $client->forms->analytics($form['id'], days: 30);$starters = $client->forms->listStarters(); $client->forms->pause($form['id']);$client->forms->resume($form['id']);$copy = $client->forms->duplicate($form['id']);$client->forms->delete($copy['id']); echo $saved['senderIssue'] ?? 'ready to send', ' ', $signup['outcome'], ' ', $stats['totals']['conversion'] ?? 'no views yet', ' ', count($starters), PHP_EOL;Un 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 la forme d'une ConflictException.
Les champs d'un formulaire sont les clés d'un tableau aux noms en camelCase de l'API (expectedUpdatedAt, doubleOptIn), alors que les filtres et les options sont des arguments nommés (status: sur listSubmissions, offsetMinutes: sur analytics). Un formulaire revient sous forme de tableau à clés en camelCase : $form['subscribeUrl'] lit donc l'adresse qui reçoit les inscriptions.
design crée un nouveau formulaire en brouillon à partir d'un brief écrit, comme Créer avec l'IA sur la page Formulaires, et redesign applique des instructions écrites au brouillon d'un formulaire, comme Demander à l'IA dans l'éditeur de formulaires. Chacun consomme une action d'IA et n'écrit que le brouillon : les visiteurs ne voient donc rien de nouveau avant publish.
La lecture exige forms:read et la modification forms:write. approveSubmission exige aussi contacts:write, car il ajoute un contact. resendConfirmation 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 une PermissionException dont isStepUpRequired() vaut 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 : apiKey: est donc ignoré. Les réponses sont son deuxième argument, un tableau dont les clés sont 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->importContacts. Au-delà de la limite, l'appel lève une RateLimitException. 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 la forme d'une ValidationException, et les fields de l'exception listent chaque réponse manquante ou invalide sous forme de tableau avec key et error, avec des raisons comme required, email et option. OpenEmail\Constants\FormFieldErrors nomme chaque raison. Le package 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\Result\Page de formulaires, du plus récent au plus ancien, sans document ni settings. listAll renvoie tous les formulaires dans un tableau, et iterate renvoie un Generator qui parcourt toutes les pages un formulaire à la fois. get, create, update, publish, pause, resume et duplicate renvoient le formulaire complet sous forme de tableau, 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\Constants\FormStatuses` 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.
documentarray- Le brouillon : les `fields` dans l'ordre, les textes de `copy` qui les entourent et le `style`.
publishedDocumentarray or null- Ce que voient les visiteurs actuellement, ou null jusqu'à la première publication.
settingsarray- Où vont les inscriptions et ce qui se passe après chacune : `audienceIds`, `doubleOptIn`, `senderAddress`, l'e-mail de confirmation, `successAction`, `redirectUrl` et `notifyAddresses`.
hasUnpublishedChangesbool- True quand le brouillon diffère de ce que voient les visiteurs. Toujours false avant la première publication.
senderIssuestring or null- Pourquoi un formulaire à double opt-in ne peut pas envoyer ses e-mails de confirmation pour le moment : `missing`, `not_sendable` ou `not_allowed`. null quand il le peut. `OpenEmail\Constants\FormSenderIssues` nomme les trois.
statsarray- `views`, `submissions`, `added`, `pending` et `lastSubmittedAt`, comptés au moment de la lecture.
Soumissions
listSubmissions pagine du plus récent au plus ancien, avec q: pour chercher dans les adresses e-mail et status: pour pending ou added, et listAllSubmissions et iterateSubmissions parcourent toutes les pages. OpenEmail\Constants\FormSubmissionStatuses nomme les deux statuts. Chaque soumission est un tableau 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.
resendConfirmation 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é.