コンテンツにスキップ

メール連携

このページでは、2FA をメールチャネルで利用するための準備と API 連携をまとめます。

目的

  • メールを使った 2FA の利点を理解する
  • NTT CPaaSポータルページで必要なテンプレート準備を把握する
  • API で emailTemplateId をどう扱うかを理解する

メールを認証チャネルに使うメリット

  • ユーザーが携帯端末にアクセスできない状況でも認証しやすい
  • 電話番号とメールアドレスの両方を確認する多要素認証の一部にできる
  • メールアドレス検証を兼ねたユーザージャーニーを構成できる

開始前の前提条件

メール連携を始める前に、次を満たしておきます。

  • NTT CPaaS の標準メール設定が完了している
  • 2FA API を利用できる
  • メール送信のドメインやテンプレート運用方針が決まっている

メール連携で 2FA を使う場合、API で必要なのは「ブロードキャストテンプレートID（emailTemplateId）」のみです。
NTT CPaaSポータルページでブロードキャストテンプレートを作成し、その番号を API で指定してください。

ブロードキャストテンプレートを作成する

Moments → Templates → Broadcast Templates で、メールチャネルのブロードキャストテンプレートを作成します。

作成時のポイント: - チャネルを Email に切り替える - 本文に {$pin} プレースホルダーを含める - 保存後のブロードキャストテンプレートIDを控える（API で emailTemplateId として使用）

API で必要なのはブロードキャストテンプレートIDだけです

emailTemplateId には、NTT CPaaSポータルページで控えたブロードキャストテンプレートIDを指定してください。例: #350140
テンプレートIDの確認方法は「テンプレートID指定＋変数利用例（推奨パターン）」をご参照ください。

1. アプリケーションを作成する

アプリケーション作成手順はセットアップを参照してください。

2. メッセージテンプレートを作成する

メール用メッセージテンプレートは、次のAPIで作成します。

POST /2fa/2/applications/{appId}/email/messages
Content-Type: application/json
Authorization: App {API_KEY}

{
    "pinType": "NUMERIC",
    "pinLength": 4,
    "emailTemplateId": 350140
}

この emailTemplateId は、NTT CPaaSポータルページで控えたブロードキャストテンプレートIDと同じ値を使います。

3. PIN を送信する

メール用テンプレート作成後は、API で PIN を送信します。

POST /2fa/2/pin/email
Content-Type: application/json
Authorization: App {API_KEY}

{
    "applicationId": "YOUR_APPLICATION_ID",
    "messageId": "YOUR_MESSAGE_ID",
    "to": "user@example.com"
}

レスポンスで pinId が返ります。これは検証時に必須です。

4. PIN を検証する

返却された pinId を使って、ユーザーが受け取ったPINを検証します。

POST /2fa/2/pin/{pinId}/verify
Content-Type: application/json
Authorization: App {API_KEY}

{
    "pin": "1234"
}

検証結果が返ります。

実装時の注意

テンプレートは「ブロードキャストテンプレート」だけ意識すればよい

API でメール送信する場合、必要なのはブロードキャストテンプレートID（emailTemplateId）のみです。 （UI上でコンテンツテンプレートを流用する場合もありますが、API利用者はブロードキャストテンプレートだけ意識すれば十分です）

ブロードキャストテンプレートIDを保存する

emailTemplateId の取得元になるため、どのテンプレートIDをどの用途で使うかを運用上も管理してください。

次に読む