API送信

目的

個別ユーザ向けのリアルタイム送信を実装する
トランザクションメールを安全に送る

送信方式の使い分け

項目	API送信	ブロードキャスト
主用途	個別送信	一括送信
ユースケース	個別、即時、システム連動	一括、予約、キャンペーン配信
実行タイミング	即時	スケジュール
ウォームアップ	手動	自動もしくは手動
送信トリガー	ユーザアクション	配信リストを用意

フロー

sequenceDiagram
  participant App as アプリケーション
  participant API as NTT CPaaS API
  participant MTA as 配信基盤
  participant User as 受信者

  App->>API: メール送信APIリクエスト
  API->>MTA: 配信処理
  MTA->>User: メール配信

実装の基本

送信元 sender を決める
宛先 destination を指定する
件名 subject を設定する
本文 text を設定する
必要に応じてテンプレート変数を使う

詳細なリクエストパラメータやオプションについては、メールメッセージの送信を参照してください。

実運用ではテンプレートID指定が主流です

実際の運用では、sender, subject, text などをパラメータで都度指定せず、NTT CPaaSポータルページで作成したテンプレートIDのみを指定して送信するケースが一般的です。

最小例

POST /email/4/messages
Content-Type: application/json
Authorization: App {API_KEY}

{
  "messages": [
    {
      "sender": "sender@notice.example.com",
      "destinations": [
        {
          "to": [
            {
              "destination": "user@example.com"
            }
          ]
        }
      ],
      "content": {
        "subject": "通知メール",
        "text": "NTT CPaaS から送信しています。"
      }
    }
  ]
}

テンプレートID指定＋変数利用例（推奨パターン）

実際の本番送信では、NTT CPaaSポータルサイトから送信元メールアドレス、件名、本文（HTML形式）などを含むテンプレートを作成し、API実行時にはそのテンプレートIDを指定する形が一般的です。テンプレートの作成方法はこちらをご覧ください。

テンプレートIDの取得方法

テンプレートIDは、以下のどちらかの方法でも取得できます。

NTT CPaaSポータルのテンプレート一覧画面で確認できます
メールテンプレートの取得のAPIで取得可能です

POST /email/4/messages
Content-Type: application/json
Authorization: App {API_KEY}

{
  "messages": [
    {
      "destinations": [
        {
          "to": [
            {
              "destination": "customer1@example.com",
              "placeholders": "{\"name\": \"田中一郎\", \"address\": \"東京都○○\"}"
            },
            {
              "destination": "customer2@example.com",
              "placeholders": "{\"name\": \"鈴木二郎\", \"address\": \"大阪府xx\"}"
            }
          ]
        }
      ],
      "content": {
        "templateId": "your-template-id-123",
        "defaultPlaceholders": "{\"companyName\": \"サンプル株式会社\", \"supportContact\": \"support@example.com\"}"
      }
    }
  ]
}

placeholdersやdefaultPlaceholdersパラメータで指定した宛先ごとのプレースホルダー値はテンプレート本文内で {$name} や {$address} のように呼び出すことでメール本文に挿入されます。

実装時の注意

本番では送信元を固定する

機能ごとに適切な from を決め、場当たり的に変えないようにします。

リクエストログを残す

宛先
件名
テンプレートID
リクエストID
送信時刻

を記録しておくと、トラブル調査が容易になります。

冪等性を意識する

再送制御が曖昧だと、同じ通知が多重送信される恐れがあります。
アプリケーション側で送信履歴やイベントIDの管理を検討してください。

次に読む

テンプレートと変数