フォーム
`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 として送出されます。
フォームのフィールドは API の camelCase の名前のまま（expectedUpdatedAt:、doubleOptIn）、キーワード引数または 1 つの Hash として渡します。一方、フィルターとオプションは snake_case のキーワード引数です（list_submissions の status:、analytics の offset_minutes:）。フォームは Symbol キーの Hash として返るため、form[:subscribeUrl] で登録を受け付けるアドレスを読めます。
読み取りには forms:read、変更には forms:write が必要です。approve_submission は連絡先を追加するため、contacts:write も必要です。resend_confirmation には emails:send も必要で、フォームにメールを送信させる呼び出しにも同じく必要です：doubleOptIn をオンにすること、senderAddress や確認メールを設定すること、ダブルオプトインのフォームを公開または再開することがこれにあたります。delete は OAuth アクセストークンには確認コードを求めますが、API キーには求めません。トークンが確認コードを得るまで、delete は step_up_required? が true の OpenEmail::PermissionError を送出します。
subscribe は、フォームのページと同じように人を登録し、資格情報を持つクライアントからであっても資格情報を送らないため、api_key: は無視されます。回答は、フォームのフィールドキーをキーとするキーワード引数または 1 つの Hash で渡します。1 つのネットワークからの登録はすべて 10 分ごとに 40 回という上限を共有するため、多くの人の登録を中継するサーバーはすぐに上限に達します：すでに知っている人は、代わりに audiences.import_contacts で追加してください。上限を超えると、呼び出しは OpenEmail::RateLimitError を送出します。フォームが置かれていたページを oe_source: として渡し、oe_started は省き、oe_website は空で送るか省いてください。
subscribe からの 422 は invalid_form_submission で、OpenEmail::ValidationError として送出されます。エラーの fields には、欠けているか有効でない回答がそれぞれ key と error を持つ Hash として、required、email、option などの理由とともに並びます。OpenEmail::FORM_FIELD_ERRORS がすべての理由を定義しています。gem はサーバーで動きます。ブラウザーは、フォームの subscribeUrl に回答を自分で送信します。JSON のボディとして送るか Accept: application/json ヘッダーを付ければ、どのオリジンからでも JSON が返ります。どちらもない場合は、ホストされたページへの 303 リダイレクトが返ります。
レスポンス：フォーム
list は document と settings を除いたフォームの OpenEmail::Page を新しい順で 1 つ返し、list_all と iterate はすべてのページをたどります。get、create、update、publish、pause、resume、duplicate は、document、publishedDocument、settings、audiences、senderIssue、senderProblem を加えたフォーム全体を Hash として返します。
idString- 永続的なハンドル。`frm_` に続く 24 文字の 16 進数です。
statusString- 最初の公開までは `draft`、その後は登録を受け付けている間は `live`、受け付けていない間は `paused` です。フォームが `draft` に戻ることはありません。`OpenEmail::FORM_STATUSES` がこの 3 つを定義しています。
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` がこの 3 つを定義しています。
statsHash- `views`、`submissions`、`added`、`pending`、`lastSubmittedAt`。読み取った時点で数えられます。
回答
list_submissions は、メールアドレスを検索する q: と、pending か added を指定する status: を使って新しい順にページを返し、list_all_submissions と iterate_submissions はすべてのページをたどります。OpenEmail::FORM_SUBMISSION_STATUSES が 2 つのステータスを定義しています。各回答は、送信されたとおりの内容をラベルも含めて保持する Hash なので、フォームを変更したあとも正しく読めます。
resend_confirmation は confirmationSent 付きの回答を返します。何も送られなかった場合は false です：1 つのアドレスに送られる確認メールは、フォームごとに 10 分に 1 通、ワークスペース全体で 1 日 5 通までで、追加済みの回答には送られません。expired は、最新のリンクの有効期限が切れた確認待ちの登録を示します。