お問い合わせAPIの共通仕様

AWS版と自前サーバー版は、入力検証、Turnstileの検証、送信枠の確保、SMTP送信、結果判定に同じ処理を使う。バックエンドは配置時に選び、ブラウザーから選択するパラメーターは設けない。

接続先と要求

内部の受付パスは両方式ともPOST /contactである。AWS版はAPI Gatewayの出力URL、自前版は公開プロキシのhttps://www.tectas.co.jp/api/contactなどを、サイトのPUBLIC_CONTACT_API_URLに設定する。公開パスが異なっても要求・応答の形式は変えない。

Content-Type: application/jsonと、許可したサイトのOriginを必要とする。本文の上限はUTF-8で32 KiB。未知の項目を含む要求は拒否する。Cookieや投稿者のログイン認証は使わず、Turnstileと件数制限を併用する。

{
  "requestId": "a6d3e034-1dd7-49c8-83d0-20b5d05363be",
  "turnstileToken": "ブラウザーで取得したトークン",
  "category": "その他",
  "company": "",
  "name": "テスト 太郎",
  "email": "visitor@example.com",
  "phone": "",
  "message": "問い合わせ本文",
  "consent": true
}

入力項目の文字数と必須条件は仕様書に従う。requestIdはUUID v4、turnstileTokenは1〜2048文字、consentは真偽値のtrueに限定する。文字数はUTF-16コード単位で数える。宛先・送信元はサーバーの設定で固定し、入力されたメールアドレスはReply-Toだけに使用する。

自前版のローカル検証に限り、サーバー設定TURNSTILE_ENABLED=falseでトークン検証を省略できる。この場合はturnstileTokenを空文字または省略として受け付ける。無効化を要求本文から指定することはできない。フロント側の設定と復帰手順は自前版セットアップを参照する。AWS版は常にトークンを必要とする。

応答

APIの処理結果はJSONで返し、Cache-Control: no-storeを付ける。receiptIdは要求ごとに発行するログ照合用IDであり、重複判定用のrequestIdとは異なる。

{ "code": "sent", "receiptId": "ログ照合用のUUID" }
HTTPステータス code 意味
200 sent SMTPの受付と成功記録を確認済み。受信箱への配送完了を保証するものではない
400 invalid_input JSONまたは入力項目が不正。項目を特定できる場合はerrorsに項目名とメッセージを返す
403 origin_rejected / verification_failed Origin不一致/Turnstile検証失敗
405 method_not_allowed POST以外の送信操作
409 processing 同じ要求が処理中、または処理中に停止した記録あり
409 request_conflict / delivery_unknown 同じIDで入力が異なる/送信結果が不明
413 / 415 payload_too_large / unsupported_media_type 本文サイズ超過/JSON以外
429 rate_limited 時間・日単位の送信枠を超過
502 delivery_failed SMTPの明確な拒否など、送信失敗を確認
503 dependency_error / delivery_unknown 停止設定、依存先障害、処理数超過/送信結果や記録を確定できない

API Gateway・nginx・ネットワーク機器が先に拒否した場合は、上のJSON形式にならないことがある。画面は応答形式の異常や通信断を成功と扱わず、同じIDで結果を確認する。CORSの事前要求はAPI Gatewayまたは自前版のHTTPサーバーが扱い、許可したOriginにPOSTとContent-Typeの利用を認める。

件数制限と再試行

Toの固定宛先は1件以上とし、サーバーのMAIL_TO(AWSのMailTo)にカンマ区切りで設定する。メールは1回のSMTP送信で全宛先に指定し、Cc・Bccは使わない。受信者にはTo一覧が見える。宛先数によらず、新規問い合わせ1件で送信枠を1件消費する。

sentは設定した全宛先のSMTP受付を確認し、成功を記録できた場合だけ返す。一部の宛先だけ受け付けられた場合はUNKNOWNを記録し、503・delivery_unknownを返す。全員への再送は受信済みの相手へ重複するため行わず、管理者がSMTP側・各受信先で確認する。全宛先への明確な拒否は従来どおりdelivery_failedとして扱う。SMTP受付後の受信箱への到達までは保証しない。Nodemailerの複数宛先の扱い

全体上限の初期値はJSTの毎時10件・1日30件、IP別上限は毎時3件・1日10件である。新規IDの予約と全体・IP別の4カウンターの加算を同じトランザクションで行い、失敗時はSMTP送信に進まない。送信枠の確保後にSMTPが失敗しても件数を戻さない。IPは信頼するプロキシまたはAPI Gatewayの接続情報から取得し、HMAC化した値をカウンターのキーに使う。生のIPはDB・アプリログへ保存しない。設定と残る制約は受付制限と停止攻撃への対策を参照する。

同じIDと入力に成功記録があれば、再送せずsentを返す。照合には秘密鍵付きHMACを使い、氏名・メールアドレス・本文はDBに保存しない。記録の保持期間は7日。AWS版はDynamoDBのTTL、自前版は起動時と1時間ごとの削除処理で期限切れデータを整理する。削除完了までは既存記録を参照する。

処理状態はPENDING、SENT、FAILED、UNKNOWNの4つとする。PENDINGやUNKNOWNを時間経過だけで再送可能に変更しない。成否不明時は受信側・ログで確認し、二重送信を避ける。FAILEDの場合のみ、利用者の次の手動操作で新しいIDを使う。

バックエンドの選択と切り替え

選択 起動入口 保存先 秘密情報 構築手順
AWS Lambdaのsrc/index.handler DynamoDB Secrets Manager AWSセットアップ
自前サーバー Node.jsのsrc/server.mjs SQLite 非公開のJSONファイル 自前サーバーのセットアップ

フロントは接続先URLを設定し直して再ビルド・配置する。同じ公開URLを維持する場合はプロキシの転送先で切り替えられるが、接続先の検証は必要になる。Turnstileは許可ホスト名が変わらなければ同じキーを使える。

両DBの記録は自動同期・自動移行しない。切り替える際は旧APIの新規送信を止め、開始済みの処理を確認してから接続先を変更する。別DBで運用を始めるとカウンターと重複判定が引き継がれないため、当日の上限を残数に合わせるなどの調整を行う。成否不明の投稿は新しいAPIで再送せず、管理者が個別に確認する。記録を移す場合はHMAC秘密鍵も一致させ、専用の移行手順を用意する。