本文へスキップ

開発者ガイド · 購読フォーム

独自の購読体験を作る。

独自の HTML、スタイル、ウェブフレームワークをそのまま使えます。公開購読エンドポイントを通じて、独自フォームを公開済みの smartest.email フォームに接続できます。

このガイドの内容

公開フォームの設定と任意のウェブサイトオリジンからの購読登録

同意、検証、レスポンス、レート制限

フォームに表示される URL を使用します。

購読フォームでフォームを作成し、必須のメール項目と同意チェックボックスを設定して公開します。「設置」タブにそのフォームの正確な URL が表示されます。

ベース URL

https://api.smartest.email/api/v1/public/forms/{FORM_ID}

フォームの「設置」タブに表示される URL を使用してください。以下の例では、FORM_ID を公開済みフォームの ID に置き換えます。

1

作成

項目と分かりやすい同意文言を設定します。

2

公開

新しいフォームは下書きで作成され、公開するまで公開ルートは404を返します。

3

連携

埋め込みコードを使うか、以下の二つの公開エンドポイントを呼び出します。

独自の HTML フォームを使う。

直接送信に対応しています。smartest.email でフォームを作成・公開して項目と同意文言を定義し、既存のサイトフォームでその ID を使用します。ウィジェットを設置せず、埋め込み型のフォームを選ぶこともできます。

サイトから JavaScript の fetch()で送信するか、自分のサーバーで購読を JSON として転送できます。公開エンドポイントに API キー、アクセストークン、smartest.email の埋め込みスクリプトは不要です。

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

FORM_ID を公開済みフォームの UUID に置き換え、以下の本文を Content-Type: application/json で送信してください。

JSON リクエスト · 訪問者の同意後
{
  "data": {
    "email": "visitor@example.com"
  },
  "consent": true
}

設定する consent には訪問者の明示的な選択を反映し、フォームの同意文言とプライバシーに関する通知を表示してください。 consent は最上位に置き、設定した連絡先項目は data内に入れます。公開済みフォームの必須項目をすべて含めてください。

通常の HTML フォーム送信にはアダプターが必要です

このエンドポイントは JSON のみ受け付けます。通常の <form method="post" action="…"> は URL エンコードまたは multipart データを送信し、 415 JSON body requiredを受け取ります。以下の ブラウザー JavaScript の例を使うか、自分のサーバーに送信し、そこから smartest.email へ JSON を送ってください。

取得する 公開設定 を使えば、ラベルと検証を公開済みフォームと一致させられます。送信のたびに取得する必要はありません。成功メッセージやリダイレクトは連携側で処理してください。このエンドポイントは常に JSON を返します。

公開した項目を表示する。

この公開エンドポイントにアクセストークンは不要です。フォームを表示するときに取得し、返された項目名、同意文言、プライバシー URL を独自画面で使います。

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}

有効なフォームの安全な表示用データと200を返します。取得に成功するたび閲覧数が増えるため、ポーリングは避けてください。

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.js

既製のインライン・ポップアップウィジェット用スクリプトです。独自画面が不要な場合、「設置」の正確なスクリプト URL を使用します。

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landing

有効なフォームのホスト型購読ページです。

GET /api/v1/public/forms/{FORM_ID} · レスポンス例
{
  "id": "FORM_ID",
  "name": "Newsletter",
  "organizationName": "Example Studio",
  "type": "embedded",
  "fields": [
    { "name": "email", "type": "email", "label": "Email address", "required": true },
    { "name": "consent", "type": "checkbox", "label": "I agree to receive email updates.", "required": true }
  ],
  "styling": {},
  "successAction": {},
  "privacyUrl": "https://example.com/privacy"
}

レスポンスには、追加設定された項目、選択肢、検証ルールが含まれる場合があります。 successAction は既製ウィジェットの動作を示します。直接送信では以下の汎用 JSON レスポンスを返します。下書き、未公開、無効、不明なフォームのスクリプトとホスト型ページは404を返します。

データと一緒に同意を送る。

訪問者がマーケティングメールの受信を明示的に選択した後に JSON を送信します。同意フラグは最上位に置き、consent を data 内に入れないでください。

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

アクセストークンは不要です。Content-Type: application/json と {data:{email:...},consent:true} を送信します。新規・既存アドレスの両方に同じ汎用成功レスポンスを返します。

HTML + ブラウザー JavaScript · メールと同意のフォーム
<form id="signup-form">
  <fieldset id="signup-fields" disabled>
    <legend>Subscribe to email updates</legend>
    <label id="email-label" for="signup-email">Email address</label>
    <input id="signup-email" type="email" autocomplete="email" required>
    <label for="signup-consent">
      <input id="signup-consent" type="checkbox" required>
      <span id="consent-label"></span>
    </label>
    <a id="privacy-link" href="/privacy">Privacy notice</a>
    <button id="signup-submit" type="submit">Subscribe</button>
  </fieldset>
  <p id="signup-status" role="status" aria-live="polite"></p>
</form>
<script type="module">
  const endpoint = "https://api.smartest.email/api/v1/public/forms/FORM_ID";
  const form = document.querySelector("#signup-form");
  const fields = document.querySelector("#signup-fields");
  const button = document.querySelector("#signup-submit");
  const status = document.querySelector("#signup-status");
  let ready = false;
  let submitting = false;

  form.addEventListener("submit", async event => {
    event.preventDefault();
    if (!ready || submitting || !form.reportValidity()) return;
    submitting = true;
    button.disabled = true;
    try {
      const response = await fetch(endpoint + "/submit", {
        method: "POST",
        credentials: "omit",
        headers: { "Content-Type": "application/json", "Accept": "application/json" },
        body: JSON.stringify({
          data: { email: document.querySelector("#signup-email").value.trim() },
          consent: document.querySelector("#signup-consent").checked
        })
      });
      const result = await response.json();
      status.textContent = result.message || "Please try again.";
      if (response.ok) form.reset();
    } catch {
      status.textContent = "Please try again.";
    } finally {
      submitting = false;
      button.disabled = false;
    }
  });

  try {
    const response = await fetch(endpoint, { credentials: "omit" });
    if (!response.ok) throw new Error("Signup form unavailable");
    const config = await response.json();
    document.querySelector("#email-label").textContent =
      config.fields.find(field => field.name === "email").label;
    document.querySelector("#consent-label").textContent =
      config.fields.find(field => field.name === "consent").label;
    if (config.privacyUrl) {
      document.querySelector("#privacy-link").href = config.privacyUrl;
    }
    ready = true;
    fields.disabled = false;
  } catch (error) {
    status.textContent = error.message;
  }
</script>

置き換える FORM_ID にはフォームの UUID を指定します。フォールバックの /privacy リンクは、フォームに privacyUrlが未設定の場合、自分の通知ページに設定してください。この例は必須の二つの項目を扱います。公開済み設定に他の必須項目がある場合は表示して送信してください。

受理レスポンス

JSON
{"success":true,"message":"Thank you for subscribing."}

アドレスが既に存在するかどうかは意図的に返しません。既存の購読中・購読解除済み連絡先の状態は維持され、新しく受理されたアドレスだけが購読者と同意記録を追加します。

公開済みの fields 配列にある名前だけを送ってください。必須項目は必ず指定します。追加項目ではチェックボックスは真偽値、数値は数値の文字列、日付は YYYY-MM-DDで送ります。選択・ラジオ項目の値は optionsの記載と完全一致させます。API はサーバー側でも再検証します。

任意の最上位プロパティ website はスパム対策用ハニーポットです。通常は省略するか空にしてください。値がある場合は連絡先を追加せず汎用成功レスポンスを返します。訪問者のサイト URL を入れる項目ではありません。

エラーと通信量の制限に対応。

公開フォームのエンドポイントは、外部サイトから Content-Type と Accept ヘッダーを使うクロスオリジンの GET、POST、OPTIONS を許可します。ブラウザーからは credentials: omit を使用してください。アカウント Cookie、Authorization ヘッダー、API キーは不要です。

ステータス意味
200設定取得または送信受理。重複アドレスにも同じ送信レスポンスを返します。
400 / 415不正な JSON、またはリクエスト形式が次と異なります: application/json.
404不明、下書き、未公開、無効なフォーム。
409アカウントの連絡先上限に達しています。
413 / 422本文が16 KiBを超える、または同意・項目データが無効。
429レート制限に達しました。ブラウザー側では JSON 本文の retry_after を利用できます。サーバー連携では次も参照できます: Retry-After.

エラーは {"error":true,"message":"..."}を使います。レート制限エラーにはさらに retry_after の値は秒単位です。フォームへのリクエストは IP ごとに毎分最大 30 回で、そのうち送信は最大 10 回までです。サイトのコンテンツセキュリティポリシーでは、次へのアクセスを許可する必要があります: https://api.smartest.email を connect-srcで許可してください。既製の埋め込みでも次の許可が必要です: script-src.

自分のサーバーで送信を転送する場合、リクエスト数の制限では、そのサーバーの送信元 IP を共有してカウントされます。

同意と配信

新しい購読を受理すると購読中の連絡先を作成し、フォームの同意文言、時刻、指定されたリクエスト元を保存します。独自画面は送信前に同意文言とプライバシー通知を表示する必要があります。リクエスト元の記録は本人確認の証拠ではありません。このエンドポイントはシングルオプトインで、確認メールの送信やアドレス所有権の検証は行いません。