コンテンツにスキップ

API送信

目的

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

向いている用途

  • パスワード再設定
  • 認証コード通知
  • 注文完了通知
  • システムアラート
  • 個別リマインド

フロー

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

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

実装の基本

  1. 送信元 from を決める
  2. 宛先 to を指定する
  3. 件名 subject を設定する
  4. 本文 text / html を設定する
  5. 必要に応じてテンプレート変数を使う

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

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

実際の運用では、from や subject などをパラメータで都度指定せず、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指定＋変数利用例（推奨パターン）

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

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

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

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

テンプレート本文内で {$name} や {$address} のように呼び出せます。

テンプレート変数の詳細はこちら

テンプレート変数やプレースホルダーの詳細な仕様・使い方はテンプレートと変数もご参照ください。

実装時の注意

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

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

リクエストログを残す

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

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

冪等性を意識する

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

使い分け

送信方式 向いているケース
API送信 個別、即時、システム連動
ブロードキャスト 一括、予約、キャンペーン配信

次に読む