Formulare
`forms->list`, `listAll`, `iterate`, `get`, `create`, `design`, `redesign`, `update`, `delete`, `publish`, `pause`, `resume`, `duplicate`, `analytics`, `listStarters`, `getStarter`, `listSubmissions`, `getSubmission`, `deleteSubmission`, `deleteSubmissions`, `approveSubmission`, `resendConfirmation` und `subscribe`.
Jede Methode
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;Ein Formular hat einen Entwurf in document und das publishedDocument, das Besucher sehen. update ändert den Entwurf und die Einstellungen, und publish schaltet den Entwurf live. Einstellungen gelten sofort, ob veröffentlicht oder nicht, und expectedUpdatedAt lehnt eine Speicherung, die die einer anderen Person überschreiben würde, mit einem 409 version_conflict ab, geworfen als ConflictException.
Die Felder eines Formulars sind die Schlüssel eines Arrays mit den camelCase-Namen der API (expectedUpdatedAt, doubleOptIn), während Filter und Optionen benannte Argumente sind (status: bei listSubmissions, offsetMinutes: bei analytics). Ein Formular kommt als Array mit camelCase-Schlüsseln zurück, $form['subscribeUrl'] liest also die Adresse, die Anmeldungen annimmt.
design baut aus einem schriftlichen Briefing ein neues Formular als Entwurf, wie „Mit KI erstellen“ auf der Seite „Formulare“, und redesign wendet schriftliche Anweisungen auf den Entwurf eines Formulars an, wie „KI fragen“ im Formular-Builder. Jeder Aufruf verbraucht eine KI-Aktion und schreibt nur den Entwurf, Besucher sehen also nichts Neues bis zu publish.
Lesen erfordert forms:read und Ändern erfordert forms:write. approveSubmission erfordert außerdem contacts:write, weil es einen Kontakt hinzufügt. resendConfirmation erfordert außerdem emails:send, ebenso ein Aufruf, durch den das Formular E-Mails sendet: doubleOptIn einschalten, senderAddress oder die Bestätigungs-E-Mail festlegen oder ein Formular mit Double-Opt-in veröffentlichen oder fortsetzen. delete verlangt von einem OAuth-Zugriffstoken einen Bestätigungscode, von einem API-Schlüssel nie. Solange das Token keinen hat, wirft delete eine PermissionException, deren isStepUpRequired() true ist.
subscribe meldet jemanden so an, wie es die Seite des Formulars tut, und sendet keine Zugangsdaten, auch nicht von einem Client, der welche hat. apiKey: wird daher ignoriert. Die Antworten sind sein zweites Argument, ein Array, geschlüsselt nach den Feldschlüsseln des Formulars. Alle Anmeldungen aus einem Netzwerk teilen sich ein Limit von 40 alle zehn Minuten, ein Server, der Anmeldungen für viele Personen weiterreicht, erreicht es also schnell: Fügen Sie Personen, die Sie bereits kennen, stattdessen mit audiences->importContacts hinzu. Über dem Limit wirft der Aufruf eine RateLimitException. Übergeben Sie die Seite, auf der das Formular war, als oe_source, lassen Sie oe_started weg und senden Sie oe_website leer oder gar nicht.
Ein 422 von subscribe ist invalid_form_submission, geworfen als ValidationException, und fields der Exception listet jede fehlende oder ungültige Antwort als Array mit key und error auf, mit Gründen wie required, email und option. OpenEmail\Constants\FormFieldErrors nennt jeden Grund. Das Paket läuft auf einem Server. Ein Browser sendet die Antworten selbst an die subscribeUrl des Formulars, als JSON-Body oder mit einem Header Accept: application/json, und bekommt von jedem Origin JSON zurück. Fehlt beides, bekommt er eine 303-Weiterleitung auf die gehostete Seite.
Antwort: ein Formular
list gibt eine OpenEmail\Result\Page mit Formularen zurück, neueste zuerst, ohne document und settings. listAll gibt alle Formulare in einem Array zurück, und iterate gibt einen Generator zurück, der alle Seiten Formular für Formular durchläuft. get, create, update, publish, pause, resume und duplicate geben das ganze Formular als Array zurück, das document, publishedDocument, settings, audiences, senderIssue und senderProblem ergänzt.
idstring- Der dauerhafte Bezeichner, `frm_` gefolgt von 24 Hexzeichen.
statusstring- `draft` bis zur ersten Veröffentlichung, dann `live`, solange es Anmeldungen annimmt, und `paused`, solange es keine annimmt. Ein Formular kehrt nie zu `draft` zurück. `OpenEmail\Constants\FormStatuses` nennt die drei.
urlstring- Die gehostete Seite des veröffentlichten Formulars, zum Teilen als Link.
subscribeUrlstring- Wohin ein reines HTML-Formular oder ein Skript im Browser die Antworten sendet.
documentarray- Der Entwurf: `fields` in ihrer Reihenfolge, die umgebenden Texte in `copy` und der `style`.
publishedDocumentarray or null- Was Besucher jetzt sehen, oder null bis zur ersten Veröffentlichung.
settingsarray- Wohin Anmeldungen gehen und was danach geschieht: `audienceIds`, `doubleOptIn`, `senderAddress`, die Bestätigungs-E-Mail, `successAction`, `redirectUrl` und `notifyAddresses`.
hasUnpublishedChangesbool- True, wenn sich der Entwurf von dem unterscheidet, was Besucher sehen. Vor der ersten Veröffentlichung immer false.
senderIssuestring or null- Warum ein Formular mit Double-Opt-in seine Bestätigungs-E-Mails gerade nicht senden kann: `missing`, `not_sendable` oder `not_allowed`. null, wenn es das kann. `OpenEmail\Constants\FormSenderIssues` nennt die drei.
statsarray- `views`, `submissions`, `added`, `pending` und `lastSubmittedAt`, gezählt im Moment des Lesens.
Einsendungen
listSubmissions liefert Seiten, neueste zuerst, mit q: zum Durchsuchen von E-Mail-Adressen und status: für pending oder added, und listAllSubmissions und iterateSubmissions durchlaufen alle Seiten. OpenEmail\Constants\FormSubmissionStatuses nennt die beiden Status. Jede Einsendung ist ein Array, das die Antworten so behält, wie sie gesendet wurden, samt Bezeichnungen, sodass sie auch nach einer Änderung des Formulars richtig lesbar bleibt.
resendConfirmation gibt die Einsendung mit confirmationSent zurück. Es ist false, wenn nichts hinausging: Eine Adresse erhält eine Bestätigung pro Formular alle zehn Minuten und fünf pro Tag im ganzen Workspace, und eine hinzugefügte Einsendung erhält keine. expired markiert eine ausstehende Anmeldung, deren neuester Link abgelaufen ist.