フォームのしくみ

フォームは、訪問者に見える内容のコピーを 2 つ保持します。document は編集する下書きで、publishedDocument はホストされたページ、埋め込み、subscribe エンドポイントが使うものです。保存で変わるのは下書きだけで、POST /forms/{id}/publish で下書きが公開中のコピーになります。hasUnpublishedChanges は、2 つが異なることを示します。

• —draft: 一度も公開されていません。誰も見ることができず、これを通じて登録することもできません。
• —live: 公開済みで、登録を受け付けています。
• —paused: 公開済みですが、受付を終了しています。ページには文面にある受付終了のメッセージが表示され、登録は拒否されます。

settings は別物です。登録の追加先、ダブルオプトイン、送信元、登録後の動作、そして各登録を誰に通知するかを扱います。公開の有無にかかわらず、保存した時点で適用されます。

ドキュメントは、fields のリスト、その周りの文面である copy、そして style からなります。各入力フィールドには key があり、これは回答が送信されるときの名前です。小文字の英字 1 文字に、小文字の英字、数字、アンダースコアが最大 39 文字続く形で、フォーム内で一意でなければならず、oe_ で始めることはできません。どのフォームにも email フィールドがちょうど 1 つあり、そのキーは email で、必須です。

• —入力: email、text、textarea、number、phone、url、date。
• —選択式: select、radio、checkboxes。いずれも options を持ちます。
• —checkbox は「はい」か「いいえ」の回答に、consent は必須のときにチェックが必要なボックスに使います。
• —audiences では、本人がリストを選べます。各選択肢の value は、このワークスペースのオーディエンス id です。
• —hidden は、訪問者には見えない値を運びます。ページが送信した値、なければその defaultValue で、たとえばキャンペーン名などです。
• —heading、paragraph、divider はフォームのレイアウトにだけ使われ、何も送信しません。

テキストフィールドで mapsTo を firstName、lastName、name のいずれかにすると、その回答が、登録によって作成される連絡先の名前になります。すでに存在する連絡先は元の名前のままです。各回答内容は当時のラベルとともに回答に保存されるため、フォームを変更したあとも古い回答は正しく読めます。

まず公開します。そのうえで、3 つのうちページに合う方法を使ってください。どれも同じフォームにつながり、登録も同じように数えられます。表示回数はホストされたページと埋め込みでしか数えられないため、自前の HTML やコードを通じた登録はコンバージョン率を押し上げます。

• —url にあるホストされたページ。どこからでもリンクできる専用のページです。
• —埋め込みスクリプト。サイズが自動で調整されるフレームに入れて、フォームをページに置きます。
• —自前の HTML やコード。回答を subscribeUrl に送信します。

<script src="https://openemail.uk/embed/form.js" data-openemail-form="frm_3b9d2e7a1c4f80d56e2a9b14" async></script>

<form action="https://api.openemail.uk/subscribe/frm_3b9d2e7a1c4f80d56e2a9b14" method="post">  <input type="email" name="email" required>  <div style="position:absolute;left:-9999px" aria-hidden="true">    <input type="text" name="oe_website" tabindex="-1" autocomplete="off">  </div>  <button type="submit">Subscribe</button></form>

プレーンな HTML フォームは、完了ページか settings.redirectUrl にリダイレクトされます。JSON を送信するコードには、代わりに JSON の応答が返ります。これは subscribe エンドポイントのページで説明しています。

settings.doubleOptIn がオンの場合、登録は pending として保存され、このワークスペースのアドレスである settings.senderAddress から本人にリンクがメールで送られます。本人がそれを開くと、オーディエンスに加わります。リンクの有効期間は 7 日間です。以前にオーディエンスの配信を停止した人が再び購読状態になるのはこの方法だけで、シングルオプトインのフォームで戻ることはありません。確認前にもう一度登録すると、新しい登録は追加されず、保留中の登録が更新されます。

メールを受け取る人を守るため、1 つのアドレスに送られる確認メールは、フォームごとに 10 分に 1 通まで、ワークスペース全体で 1 日 5 通までです。確認待ちの登録は、自分で承認することも、新しいリンクを送ることもできます。

• —読み取りには forms:read、変更には forms:write が必要です。登録の承認は連絡先を追加するため、contacts:write も必要です。
• —フォームにメールを送信させる操作には、emails:send も必要です。ダブルオプトインをオンにすること、送信元や確認メールを設定すること、ダブルオプトインのフォームを公開または再開すること、確認メールを再送信することがこれにあたります。
• —API キーと所有者には、ワークスペースのすべてのフォームが見えます。メンバーが接続したアプリに見えるのは、そのメンバーが作成したフォームと、オーディエンスのうちそのメンバーが作成したものと組み込みのものだけです。
• —送信元または通知先のアドレスが、制限付きのキーやアプリが届く範囲の外にあるフォームを作成、更新、公開、再開、複製すると、422 capability_unsupported が返ります。
• —一部のアドレスに限定されたキーやアプリは、自分が保持するアドレスしか送信元や通知先に設定できません。
• —フォームを削除するときは、他の破壊的な変更と同じく、OAuth アプリに確認コードが求められます。API キーには必要ありません。

form.submitted と form.confirmed の Webhook が、すべての登録をあなたのシステムに知らせます。登録はワークスペース全体に属するため、一部のアドレスに限定された Webhook にはこれらは届きません。

• —oe_website という名前のフィールドはボット用の罠です。上の HTML のように、空のまま画面外に置いてください。これを埋めた登録には通常の応答が返りますが、破棄されます。
• —ホストされたページと埋め込みは、署名付きの開始時刻もチェックします。人が記入できるより速く送り返されたフォームも、同じように破棄されます。
• —1 つのネットワークが送信できる登録は、すべてのフォームを通じて、結果にかかわらず 10 分間に 40 回までです。それを超えると、JSON で呼び出す側には 429 form_rate_limited が返り、プレーンな HTML フォームは ?outcome=limited 付きでホストされたページに移動します。
• —1 つのワークスペースが持てるフォームは、既定で 100 件です。

ここにあるものはすべて、SDK では openemail.forms、CLI では openemail forms としても使え、MCP サーバーにはフォームのツールがあるため、エージェントがフォームを作成し、公開し、見守ることができます。MCP では、クライアントが自分でデザインを書き、document として渡します。

自分のコードから subscribeUrl に送信する場合、資格情報は不要です。回答は JSON で送り、フォームが置かれていたページを oe_source として加え、oe_started は省き、oe_website は空で送るか省いてください。1 つのネットワークからの登録はすべて 10 分ごとに 40 回という上限を共有するため、多くの人の登録を中継するサーバーはすぐに上限に達します。すでに知っている人は、代わりにオーディエンスのインポートで追加してください。