• No : 144
  • 公開日時 : 2024/11/22 00:00
  • 更新日時 : 2025/05/09 00:00
  • 印刷

即時配信メールAPIを実装したい

カテゴリー : 

回答

即時配信メールAPIとは

本APIの概要

即時配信メールAPIとは、貴社の基幹システム/アプリケーションとb→dashを繋ぐことで、「購入完了」「登録完了」したタイミングにb→dashで作成したコンテンツを即時で配信することができるAPIです。

即時配信メールの配信を行いたい場合は、本API仕様書をご参照のもと貴社開発環境に実装してください。

本API利用にあたっての前提事項

共通仕様

即時配信メールAPIでは、b→dash APIの共通仕様も参照する必要があります。共通仕様の詳細については「b→dash APIの共通仕様を知りたい」をご参照ください。

非機能要件

即時配信メールAPIでは、下記の非機能要件を持ちます。「分間リクエスト上限数」の項目のみb→dashAPIの共通仕様と異なるため、ご確認ください。

# 項目 非機能要件
1 全体サイズ上限 3MBまで 
(共通仕様同様)
2 レスポンス リクエストからレスポンスの間は5秒以内 
(共通仕様同様)
3 分間リクエスト上限数 2000リクエスト 
（2000リクエストを超えた場合は、『429エラー』は表示されます。） 

※「分間リクエスト上限数」のみ共通仕様と異なります
4 同時接続上限数 5リクエストまで 
(共通仕様同様)
5 タイムアウト 60秒まで
(共通仕様同様)

※上限数は、1アカウント内の上限とします

即時配信メールAPIの仕様

処理フロー図

即時配信メールAPIの処理フロー図は以下になります。

リクエスト

リクエストボディパラメータを指定して、メール配信設定の内容を送信するためのリクエストボディを準備します。

〇リクエストボディパラメータ

プロパティ データ型 
/サイズ		 必須 説明
email string 
/-		 ○ 配信先のアドレス
insert_params object 
/-		 - 「パラメータ挿入」の設定 
（複数設定可）

【リクエストボディサンプル】

{
 "email": "example@example.com",
 "insert_params": {
    "value1": "name",
    "value2": "date"
 }
}
リクエストボディパラメータを実装する際の注意点
実装する際に入力する内容

リクエストボディパラメータを実装する際は、上記サンプルのように「value1」「value2」「value3」…と指定してください。

「key」に関する注意点

※「key」とは、上記の【リクエストボディサンプル】に記載されている「email」や「value1」などの値を指します

● 利用することができる文字列　　　：『半角の英数字』『_（アンダースコア）』
● 設定することができる文字数の上限：『50文字』
● 設定できる「key」の上限　　 　　：『50個』

「value」に関する注意点

※「value」とは、上記の【リクエストボディサンプル】に記載されている「name」や「date」などの値を指します

● 利用することができる文字コード：『UTF-8』

即時配信メールAPIのURLと、準備したリクエストボディ、下記のリクエストヘッダパラメータを用いて、貴社サイトから「POST」リクエスト形式で即時配信メールのリクエストをします。

〇即時配信メールAPIのURL

URI https://api.smart-bdash.com/api/v1/realtime_mail/{:ID}/send

〇リクエスト形式

HTTPメソッド POST

〇リクエストヘッダパラメータ

プロパティ 型 
/サイズ		 必須 値 説明
Authorization - - - 『Bearer {発行したAPIキー}』を指定してください。
Content-type - - - 『application/json; charset=UTF-8』" を指定してください。

【リクエストコードサンプル】

POST https://api.smart-bdash.com/api/v1/realtime_mail/1001/send

レスポンス

リクエストの送信に成功すると、下記のレスポンス形式で即時配信メールのレスポンスが返されます。

〇レスポンスボディパラメータ

パラメータ名 データ型 説明
階層1：result object -
階層2：code integer($int32) ステータスコード 
・リクエスト成功：「202」 
・リクエストエラー：「400」「401」「403」 
　　　　　　　　　　「404」「413」「414」 
　　　　　　　　　　「429」「500」
階層3：transaction_id string 配信結果を確認するために利用するID
階層4：errors object[] エラーの配列
階層5：message string エラーメッセージ

【レスポンスボディサンプル（成功レスポンス（202））】

{
  "result": {
    "code": 202,
　  "transaction_id": 1001,
　  "errors": [
   ]
  }
}

○リクエストエラー発生時のエラーメッセージ詳細

「階層4：errors」には、具体的に以下のようなメッセージが格納されます。

# ステータス 
コード		 レスポンス 説明
1 400 { 
  "result": { 
    "code": 400, 
    "errors": [ 
      { 
        "message": "{必須パラメーター} is missing" 
      } 
    ] 
  } 
}		 必須項目の指定がない。
2 400 { 
  "result": { 
    "code": 400, 
    "errors": [ 
      { 
        "message": "insert_params is over the limit of 50." 
      } 
    ] 
  } 
}		 insert_params配下のキーの数が 
51個以上ある。
3 400 { 
  "result": { 
    "code": 400, 
    "errors": [ 
      { 
        "message": "email is invalid format." 
      } 
    ] 
  } 
}		 受信者アドレスの形式が、 
メールアドレスの形式に一致していない。
4 400 { 
  "result": { 
    "code": 400, 
    "errors": [ 
      { 
        "message": "Available campaign not found." 
      } 
    ] 
  } 
}		 ・利用する配信設定が削除されている、もしくは存在しない。 

・運用のステータスが「運用中」ではない。
5 400 { 
  "result": { 
    "code": 400, 
    "errors": [ 
      { 
        "message": "Campaign not started." 
      } 
    ] 
  } 
}		 運用開始日を迎えていない。
6 401 { 
  "result": { 
    "code": 401, 
    "errors": [ 
      { 
        "message": "insert_params is over the limit of 50." 
      } 
    ] 
  } 
}		 Header不正による認証エラー。
7 403 { 
  "result": { 
    "code": 403, 
    "errors": [ 
      { 
        "message": "Do not have permission to access." 
      } 
    ] 
  } 
}		 アクセス権がない。
8 413 { 
  "result": { 
    "code": 413, 
    "errors": [ 
      { 
        "message": "The request payload is larger than the server is willing or able to process." 
      } 
    ] 
  } 
}		 リクエストの本体が、 
サーバーで定めている上限を超えている。
9 414 { 
  "result": { 
    "code": 414, 
    "errors": [ 
      { 
        "message": "The request is longer than the server is willing to interpret." 
      } 
    ] 
  } 
}		 リクエストしたURIが、 
サーバーで扱える長さを超えている。
10 429 { 
  "result": { 
    "code": 429, 
    "errors": [ 
      { 
        "message": "API usage limit exceeded." 
      } 
    ] 
  } 
}		 APIコール数（使用制限）の超過。
11 500 { 
  "result": { 
    "code": 500, 
    "errors": [ 
      { 
        "message": "Internal Server Error" 
      } 
    ] 
  } 
}		 b→dashシステム側のサーバーエラー。
『202』のステータスコードが返却された場合でも、メールが配信されないケースがあります

以下のいずれかに該当した場合、b→dashから即時配信メールが配信されないものの、「即時配信メールAPI」へのリクエストは成功しているため、ステータスコード『202』（リクエスト成功）が返却されます。

・配信スキップの設定により、b→dash内で配信が除外された場合
・配信対象外データファイルにより、b→dash内で配信が除外された場合
・配信対象外データファイルで指定したカラムが削除されたため、b→dash内で配信が除外された場合

上記のケースにおいて、配信されなかった実績は「メール行動ログデータ（即時配信メール）」の『行動タイプ』カラムから確認できます。
当該カラムに『mail_excluded』が格納されている場合は、即時配信メールが配信されていません。
※ メール行動ログデータ（即時配信メール）については、「b→dashデータの詳細を知りたい」の『メール行動ログデータ（即時配信メール）』をご参照ください