فرم‌ها
`forms->list`، `listAll`، `iterate`، `get`، `create`، `design`، `redesign`، `update`، `delete`، `publish`، `pause`، `resume`، `duplicate`، `analytics`، `listStarters`، `getStarter`، `listSubmissions`، `getSubmission`، `deleteSubmission`، `deleteSubmissions`، `approveSubmission`، `resendConfirmation` و `subscribe`.
همهٔ متدها
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;هر فرم یک document پیش‌نویس و publishedDocumentی را که بازدیدکنندگان می‌بینند نگه می‌دارد. update پیش‌نویس و تنظیمات را تغییر می‌دهد، و publish پیش‌نویس را منتشر می‌کند. تنظیمات بی‌درنگ اعمال می‌شوند، چه فرم منتشر شده باشد چه نه، و expectedUpdatedAt ذخیره‌ای را که روی ذخیرهٔ کس دیگری بنویسد با یک 409 version_conflict رد می‌کند که به‌صورت ConflictException پرتاب می‌شود.
فیلدهای یک فرم کلیدهای یک آرایه با نام‌های camelCase در API هستند (expectedUpdatedAt، doubleOptIn)، در حالی که فیلترها و گزینه‌ها آرگومان‌های نام‌دارند (status: روی listSubmissions، offsetMinutes: روی analytics). فرم به‌صورت یک آرایه با کلیدهای camelCase برمی‌گردد، پس $form['subscribeUrl'] نشانی‌ای را می‌خواند که ثبت‌نام‌ها را می‌پذیرد.
design از روی یک شرح نوشته‌شده یک فرم پیش‌نویس تازه می‌سازد، همان‌طور که «ساخت با هوش مصنوعی» در صفحهٔ فرم‌ها می‌کند، و redesign دستورهای نوشته‌شده را روی پیش‌نویس یک فرم اعمال می‌کند، همان‌طور که «از هوش مصنوعی بپرسید» در فرم‌ساز می‌کند. هرکدام یک کنش هوش مصنوعی مصرف می‌کند و فقط پیش‌نویس را می‌نویسد، پس بازدیدکنندگان تا publish چیز تازه‌ای نمی‌بینند.
خواندن به forms:read و تغییر دادن به forms:write نیاز دارد. approveSubmission به contacts:write هم نیاز دارد، چون یک مخاطب می‌افزاید. resendConfirmation به emails:send هم نیاز دارد، و فراخوانی‌ای که باعث شود فرم ایمیل بفرستد نیز همین‌طور: روشن کردن doubleOptIn، تنظیم senderAddress یا ایمیل تأیید، یا انتشار یا ادامهٔ یک فرم با تأیید دوگانه. delete از توکن دسترسی OAuth کد تأیید هویت می‌خواهد، و از کلید API هرگز. تا وقتی توکن کدی تأیید نکرده باشد، delete یک PermissionException پرتاب می‌کند که isStepUpRequired() آن true است.
subscribe کسی را همان‌گونه ثبت‌نام می‌کند که صفحهٔ فرم می‌کند و هیچ اعتبارنامه‌ای نمی‌فرستد، حتی از کلاینتی که اعتبارنامه دارد، پس apiKey: نادیده گرفته می‌شود. پاسخ‌ها آرگومان دوم آن هستند، یک آرایه با کلیدهای فیلدهای فرم. همهٔ ثبت‌نام‌هایی که از یک شبکه می‌آیند سقف 40 بار در هر ده دقیقه را با هم شریک‌اند، پس سروری که ثبت‌نام‌های افراد زیادی را بازارسال می‌کند زود به آن می‌رسد: افرادی را که از پیش می‌شناسید به‌جای آن با audiences->importContacts بیفزایید. پس از رسیدن به سقف، فراخوانی یک RateLimitException پرتاب می‌کند. صفحه‌ای را که فرم روی آن بود به‌صورت oe_source بدهید، oe_started را کنار بگذارید، و oe_website را خالی بفرستید یا اصلاً نفرستید.
یک 422 از subscribe همان invalid_form_submission است که به‌صورت ValidationException پرتاب می‌شود، و fields استثنا هر پاسخی را که جا افتاده یا معتبر نیست به‌صورت یک آرایه با key و error فهرست می‌کند، با دلیل‌هایی مانند required، email و option. OpenEmail\Constants\FormFieldErrors همهٔ دلیل‌ها را نام می‌برد. بسته روی سرور اجرا می‌شود. مرورگر خودش پاسخ‌ها را به‌صورت بدنهٔ JSON یا با سرآیند Accept: application/json به subscribeUrl فرم ارسال می‌کند، و از هر مبدئی JSON پس می‌گیرد. بدون هیچ‌کدام از این دو، یک هدایت 303 به صفحهٔ میزبانی‌شده می‌گیرد.
پاسخ: یک فرم
list یک OpenEmail\Result\Page از فرم‌ها برمی‌گرداند، تازه‌ترین اول، بدون document و settings. listAll همهٔ فرم‌ها را در یک آرایه برمی‌گرداند، و iterate یک Generator برمی‌گرداند که همهٔ صفحه‌ها را هر بار یک فرم می‌پیماید. get، create، update، publish، pause، resume و duplicate کل فرم را به‌صورت یک آرایه برمی‌گردانند که document، publishedDocument، settings، audiences، senderIssue و senderProblem را هم در بر دارد.
idstring- دستگیرهٔ ماندگار، `frm_` و پس از آن 24 نویسهٔ hex.
statusstring- تا نخستین انتشار `draft`، سپس `live` تا وقتی ثبت‌نام می‌پذیرد و `paused` تا وقتی نمی‌پذیرد. فرم هرگز به `draft` برنمی‌گردد. `OpenEmail\Constants\FormStatuses` این سه را نام می‌برد.
urlstring- صفحهٔ میزبانی‌شدهٔ فرم منتشرشده، برای اشتراک‌گذاری به‌صورت پیوند.
subscribeUrlstring- جایی که یک فرم HTML ساده، یا اسکریپتی در مرورگر، پاسخ‌ها را به آن ارسال می‌کند.
documentarray- پیش‌نویس: `fields` به ترتیب، `copy` پیرامونشان و `style`.
publishedDocumentarray or null- آنچه بازدیدکنندگان اکنون می‌بینند، یا null تا نخستین انتشار.
settingsarray- اینکه ثبت‌نام‌ها کجا می‌روند و پس از هر ثبت‌نام چه رخ می‌دهد: `audienceIds`، `doubleOptIn`، `senderAddress`، ایمیل تأیید، `successAction`، `redirectUrl` و `notifyAddresses`.
hasUnpublishedChangesbool- وقتی پیش‌نویس با آنچه بازدیدکنندگان می‌بینند فرق دارد true است. پیش از نخستین انتشار همیشه false است.
senderIssuestring or null- اینکه چرا یک فرم با تأیید دوگانه اکنون نمی‌تواند ایمیل‌های تأییدش را بفرستد: `missing`، `not_sendable` یا `not_allowed`. وقتی می‌تواند null است. `OpenEmail\Constants\FormSenderIssues` این سه را نام می‌برد.
statsarray- `views`، `submissions`، `added`، `pending` و `lastSubmittedAt`، که در همان لحظهٔ خواندن شمرده می‌شوند.
پاسخ‌ها
listSubmissions ثبت‌نام‌ها را صفحه به صفحه، تازه‌ترین اول، برمی‌گرداند، با q: برای جست‌وجو در نشانی‌های ایمیل و status: برای pending یا added، و listAllSubmissions و iterateSubmissions همهٔ صفحه‌ها را می‌پیمایند. OpenEmail\Constants\FormSubmissionStatuses این دو وضعیت را نام می‌برد. هر ثبت‌نام یک آرایه است که پاسخ‌ها را همان‌طور که فرستاده شدند، همراه با برچسب‌ها، نگه می‌دارد، پس پس از تغییر فرم هم درست خوانده می‌شود.
resendConfirmation ثبت‌نام را همراه با confirmationSent برمی‌گرداند. وقتی چیزی نرفته باشد false است: هر نشانی برای هر فرم یک پیام تأیید در هر ده دقیقه و در کل فضای کاری پنج پیام در روز می‌گیرد، و ثبت‌نامی که افزوده شده هیچ پیامی نمی‌گیرد. expired ثبت‌نامِ در انتظاری را نشان می‌دهد که آخرین پیوندش منقضی شده است.