فرم‌ها
`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` و `subscribe`.
همهٔ متدها
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.sizeهر فرم یک document پیش‌نویس و publishedDocumentی را که بازدیدکنندگان می‌بینند نگه می‌دارد. update پیش‌نویس و تنظیمات را تغییر می‌دهد، و publish پیش‌نویس را منتشر می‌کند. تنظیمات بی‌درنگ اعمال می‌شوند، چه فرم منتشر شده باشد چه نه، و expectedUpdatedAt ذخیره‌ای را که روی ذخیرهٔ کس دیگری بنویسد با یک 409 version_conflict رد می‌کند که به‌صورت OpenEmail::ConflictError raise می‌شود.
فیلدهای یک فرم نام‌های camelCase در API را نگه می‌دارند (expectedUpdatedAt:، doubleOptIn) و به‌صورت آرگومان‌های کلیدواژه‌ای یا یک Hash داده می‌شوند، در حالی که فیلترها و گزینه‌ها کلیدواژه‌های snake_case هستند (status: روی list_submissions، offset_minutes: روی analytics). فرم به‌صورت یک Hash با کلیدهای Symbol برمی‌گردد، پس form[:subscribeUrl] نشانی‌ای را می‌خواند که ثبت‌نام‌ها را می‌پذیرد.
خواندن به forms:read و تغییر دادن به forms:write نیاز دارد. approve_submission به contacts:write هم نیاز دارد، چون یک مخاطب می‌افزاید. resend_confirmation به emails:send هم نیاز دارد، و فراخوانی‌ای که باعث شود فرم ایمیل بفرستد نیز همین‌طور: روشن کردن doubleOptIn، تنظیم senderAddress یا ایمیل تأیید، یا انتشار یا ادامهٔ یک فرم با تأیید دوگانه. delete از توکن دسترسی OAuth کد تأیید هویت می‌خواهد، و از کلید API هرگز. تا وقتی توکن کدی تأیید نکرده باشد، delete یک OpenEmail::PermissionError با step_up_required? برابر true را raise می‌کند.
subscribe کسی را همان‌گونه ثبت‌نام می‌کند که صفحهٔ فرم می‌کند و هیچ اعتبارنامه‌ای نمی‌فرستد، حتی از کلاینتی که اعتبارنامه دارد، پس api_key: نادیده گرفته می‌شود. پاسخ‌ها به‌صورت آرگومان‌های کلیدواژه‌ای یا یک Hash داده می‌شوند، با کلیدهای فیلدهای فرم. همهٔ ثبت‌نام‌هایی که از یک شبکه می‌آیند سقف 40 بار در هر ده دقیقه را با هم شریک‌اند، پس سروری که ثبت‌نام‌های افراد زیادی را بازارسال می‌کند زود به آن می‌رسد: افرادی را که از پیش می‌شناسید به‌جای آن با audiences.import_contacts بیفزایید. پس از رسیدن به سقف، فراخوانی OpenEmail::RateLimitError را raise می‌کند. صفحه‌ای را که فرم روی آن بود به‌صورت oe_source: بدهید، oe_started را کنار بگذارید، و oe_website را خالی بفرستید یا اصلاً نفرستید.
یک 422 از subscribe همان invalid_form_submission است که به‌صورت OpenEmail::ValidationError raise می‌شود، و fields خطا هر پاسخی را که جا افتاده یا معتبر نیست به‌صورت یک Hash با key و error فهرست می‌کند، با دلیل‌هایی مانند required، email و option. OpenEmail::FORM_FIELD_ERRORS همهٔ دلیل‌ها را نام می‌برد. gem روی سرور اجرا می‌شود. مرورگر خودش پاسخ‌ها را به‌صورت بدنهٔ JSON یا با سرآیند Accept: application/json به subscribeUrl فرم ارسال می‌کند، و از هر مبدئی JSON پس می‌گیرد. بدون هیچ‌کدام از این دو، یک هدایت 303 به صفحهٔ میزبانی‌شده می‌گیرد.
پاسخ: یک فرم
list یک OpenEmail::Page از فرم‌ها برمی‌گرداند، تازه‌ترین اول، بدون document و settings، و list_all و iterate همهٔ صفحه‌ها را می‌پیمایند. get، create، update، publish، pause، resume و duplicate کل فرم را به‌صورت یک Hash برمی‌گردانند که document، publishedDocument، settings، audiences، senderIssue و senderProblem را هم در بر دارد.
idString- دستگیرهٔ ماندگار، `frm_` و پس از آن 24 نویسهٔ hex.
statusString- تا نخستین انتشار `draft`، سپس `live` تا وقتی ثبت‌نام می‌پذیرد و `paused` تا وقتی نمی‌پذیرد. فرم هرگز به `draft` برنمی‌گردد. `OpenEmail::FORM_STATUSES` این سه را نام می‌برد.
urlString- صفحهٔ میزبانی‌شدهٔ فرم منتشرشده، برای اشتراک‌گذاری به‌صورت پیوند.
subscribeUrlString- جایی که یک فرم HTML ساده، یا اسکریپتی در مرورگر، پاسخ‌ها را به آن ارسال می‌کند.
documentHash- پیش‌نویس: `fields` به ترتیب، `copy` پیرامونشان و `style`.
publishedDocumentHash or nil- آنچه بازدیدکنندگان اکنون می‌بینند، یا nil تا نخستین انتشار.
settingsHash- اینکه ثبت‌نام‌ها کجا می‌روند و پس از هر ثبت‌نام چه رخ می‌دهد: `audienceIds`، `doubleOptIn`، `senderAddress`، ایمیل تأیید، `successAction`، `redirectUrl` و `notifyAddresses`.
hasUnpublishedChangesBoolean- وقتی پیش‌نویس با آنچه بازدیدکنندگان می‌بینند فرق دارد true است. پیش از نخستین انتشار همیشه false است.
senderIssueString or nil- اینکه چرا یک فرم با تأیید دوگانه اکنون نمی‌تواند ایمیل‌های تأییدش را بفرستد: `missing`، `not_sendable` یا `not_allowed`. وقتی می‌تواند nil است. `OpenEmail::FORM_SENDER_ISSUES` این سه را نام می‌برد.
statsHash- `views`، `submissions`، `added`، `pending` و `lastSubmittedAt`، که در همان لحظهٔ خواندن شمرده می‌شوند.
پاسخ‌ها
list_submissions ثبت‌نام‌ها را صفحه به صفحه، تازه‌ترین اول، برمی‌گرداند، با q: برای جست‌وجو در نشانی‌های ایمیل و status: برای pending یا added، و list_all_submissions و iterate_submissions همهٔ صفحه‌ها را می‌پیمایند. OpenEmail::FORM_SUBMISSION_STATUSES این دو وضعیت را نام می‌برد. هر ثبت‌نام یک Hash است که پاسخ‌ها را همان‌طور که فرستاده شدند، همراه با برچسب‌ها، نگه می‌دارد، پس پس از تغییر فرم هم درست خوانده می‌شود.
resend_confirmation ثبت‌نام را همراه با confirmationSent برمی‌گرداند. وقتی چیزی نرفته باشد false است: هر نشانی برای هر فرم یک پیام تأیید در هر ده دقیقه و در کل فضای کاری پنج پیام در روز می‌گیرد، و ثبت‌نامی که افزوده شده هیچ پیامی نمی‌گیرد. expired ثبت‌نامِ در انتظاری را نشان می‌دهد که آخرین پیوندش منقضی شده است.