Transactional Email API
SMTP や APIを使用してメールを送信した際に発生するイベントデータを操作することができます。
バージョン
POSTパラメータや応答メッセージのフォーマットはAPIのバージョンによって異なります。利用するバージョンのAPI仕様を参照ください。
現在のバージョンは2です。
バージョン1のAPI仕様はこちらを参照ください。
共通仕様
このセクションでは、Transactional Email API の共通仕様について説明します。
| 項目 | 値 |
|---|---|
| プロトコル | HTTPS |
| 文字コード | UTF-8 |
| 改行コード | LF |
接続先ホストとURL
https://api.smtps.jp/transaction/[version]/[resource]/[action].[format]
[version]は、APIバージョンを表します。v2 と v1 が指定できます。[resource]は、操作対象のリソースを表します。[action]は、操作を表します。[format]は、レスポンスメッセージのフォーマットを表します。json と xml が指定できます。
認証
Transactional Email API は、HTTPリクエストに含まれる api_user, api_key パラメータを使用したユーザ認証を行います。APIユーザの登録方法については、ユーザガイドの「APIユーザ」を参照ください。
アクセス制御
各APIで、要求されるAPIユーザのロールが異なります。詳細は、各APIの「アクセス制御」の項目を参照ください。
HTTPリクエスト
このセクションでは、Transactional Email API が受信するHTTPリクエストの仕様について説明します。
HTTPリクエストの取得頻度について
HTTPリクエストの頻度について、日次での取得までは対応可能です。
日次よりも高い頻度での利用を検討されている場合は、サポートセンターまでご相談ください。
メソッド
Transactional Email API は、POSTメソッドのみを受け付けます。
ヘッダ
Transactional Email API は、以下のヘッダフィールドを参照します。
| ヘッダフィールド | 説明 |
|---|---|
| Accept-Language | Transactional Email APIが応答するメッセージの言語タイプを指定します。 en または ja のいずれかを指定します。 言語指定が無いまたは左記以外の言語を指定された場合、en で動作します。 |
コンテンツタイプ
application/x-www-form-urlencoded または application/json を指定します。
注意
application/json は、バージョン2からサポートしました。バージョン1では使用できません。
パラメータ
Transactional Email API は全てのHTTPリクエストに、ユーザ認証を行うための api_user, api_key を含める必要があり、かつ、URLごとに定義されたパラメータを送信する必要があります。
このドキュメントは以下フォーマットに従い、パラメータの説明を記述します。
| パラメータ | 必須 | データ型 | 説明 |
|---|---|---|---|
| api_user | Yes | ASCII | ユーザ認証に使用するID |
| api_key | Yes | ASCII | ユーザ認証に使用するシークレットキー |
| server_composition | Yes | UTF-8 | 操作対象となるサーバ構成の名称(サーバ構成についてはこちらを参照) |
| p | No | INTEGER | 取得するデータのページ位置。 デフォルト:0 |
| r | No | INTEGER | 取得するデータのレコード数。 デフォルト:10 |
- パラメータ：POSTするパラメータの名前。
- 必須：このパラメータが必須である場合、Yes。
- データ型：パラメータ値のデータ型。（後述、データ型を参照）
- 説明：このパラメータに関する説明。
デフォルト値、入力値の範囲などの制限があるパラメータについては、説明欄に以下の書式で記載します。
- デフォルト：(デフォルト値)
- 範囲：min=(最小値) / max=(最大値)
- 制約：パラメータに関する制約の記述。例えば、start_date は end_date と等しいか過去日でなければならないなど。
パラメータ値は文字列として受信し、長さチェックを行います。パラメータ値は最大1024文字（ASCIIの場合、1024byte, UTF-8の場合、4096byte）まで指定できます。また、必須パラメータは、最小1文字以上の値を指定する必要があります。
application/x-www-form-urlencoded を指定する場合
パラメータの名前・値のセットを作成して POST してください。
application/json を指定する場合
パラメータの名前をプロパティとした JSON を作成して POST してください。
以下は Deliveries/list APIを呼び出す JSON の例です。
{
"api_user" : "http_api_user@example.com",
"api_key" : "a29yZWhhcGFzc3dvcmRkZXN1",
"server_composition" : "sandbox",
"to" : "@example.com",
"status" : "failed",
"search_option" : {
"to" : "part",
"from" : "full",
"api_data" : "full"
}
}
データ型
Transactional Email API は以下の仕様に従い、データ型を取扱います。
| データ型 | 説明 |
|---|---|
| UTF-8 | ASCIIを含むマルチバイト文字を表します。 |
| ASCII | 印刷可能なASCII文字を表します。 |
| INTEGER | -2147483648 から 2147483647の範囲の数値を表します。 |
| DATE | YYYY-MM-DD 形式で日付を表します。DD=99である場合、指定月の末日と解釈します。 |
| TIME | HH:mm 形式で、時および分を24時間表記で表します。このAPIでは秒をリクエストパラメータとして取り扱う処理はありません。 |
| DATETIME | YYYY-MM-DD HH:mm 形式で年月日および時分を表します。 |
| BOOLEAN | true または false のいずれかを表します。 |
HTTPレスポンス
このセクションでは、Transactional Email APIが送信するHTTPレスポンスの仕様について説明します。
ステータスコード
Transactional Email APIは、以下のステータスコードを応答します。
| コード | メッセージ | 説明 |
|---|---|---|
| 200 | OK | リクエストは正常に処理されました。 |
| 204 | (メッセージはありません) | |
| 400 | Bad Request | 不正なパラメータがリクエストされたなどの理由により、リクエストは正常に処理されませんでした。 |
| 401 | Unauthorized | ユーザ認証に失敗しました。 |
| 403 | Forbidden | IP制限やアクセス制御により、ユーザからのリクエスト実行を拒否しました。 |
| 404 | Not Found | リクエストされたURLは存在しません。 |
| 500 | Internal Server Error | システム内部の問題により、リクエストを実行できませんでした。 |
ヘッダ
Transactional Email APIは、URLで指定されたフォーマットに従い、JSON または、XMLフォーマットのメッセージを応答します。また、download アクションは、ファイルダウンロードを実行します。これらの応答メッセージのフォーマットは、HTTPレスポンスヘッダ Content-Type により判別します。
| Content-Type | 説明 |
|---|---|
| application/json | JSONフォーマットのメッセージを応答します。 |
| application/xml | XMLフォーマットのメッセージを応答します。 |
| application/octet-stream | ファイルをダウンロードします。download アクションは、このフォーマットで応答します。ステータスコードが200以外の場合、リクエストで指定したフォーマットにてエラーメッセージを応答します。 |
メッセージ
Transactional Email API は以下のメッセージを応答します。
成功
このメッセージは、add / edit / delete などデータ編集を行うリクエストが成功した時に応答します。
{
"message" : "User example1.hde was deleted"
}
<message>User example1@hennge.com was deleted<message>
エラー
このメッセージは、リクエストが失敗した時に応答します。
{
"errors" : [
{
"code" : "01-004",
"field" : "api_user",
"message" : "api_user is required."
},
{
"code" : "01-004",
"field" : "api_key",
"message" : "api_key is required."
}
]
}
<errors>
<error>
<code>01-004</code>
<field>api_user</field>
<message>api_user is required.</message>
</error>
<error>
<code>01-004</code>
<field>api_key</field>
<message>api_key is required.</message>
</error>
</errors>
対象データが存在しない
list アクションなどの検索操作で対象データが存在しなかった場合、ステータスコード 204 と共に以下のメッセージを応答します。
{
"message" : "The process was finished normally but the data was not found."
}
<message>The process was finished normally but the data was not found."</message>
検索結果
list アクションなどの検索操作で対象データが存在した場合、URLごとに定めたフォーマットにてメッセージを応答します。メッセージの詳細については、各APIのマニュアルを参照ください。
エラーメッセージ
Transactional Email APIの共通エラーメッセージを以下に説明します。共通エラーメッセージ以外にも、各APIごとに定義したエラーメッセージを応答することがあります。
| コード | メッセージ (en) | メッセージ (ja) |
|---|---|---|
| 01-001 | System error was occurred. Please contact system administrator. | システムエラーが発生しました。システム管理者に連絡してください。 |
| 01-002 | HTTP Request which use GET Method is not permitted. Please use POST Method. | GETメソッドを使用したHTTPリクエストは許可していません。POSTメソッドを使用してください。 |
| 01-003 | User authentication was failed. | ユーザ認証に失敗しました。 |
| 01-004 | {0} is required. | {0}は必須項目です。 |
| 01-005 | The api_user does not have a role which is to perform requested process. | APIユーザはリクエストされた処理を実行する権限がありません。 |
| 01-101 | {0} was not found. | {0} が見つかりませんでした。 |
| 10-001 | System error was occurred. Please contact system administrator. | システムエラーが発生しました。システム管理者に連絡してください。 |
セキュリティ
このセクションでは、Transactional Email API のセキュリティについて説明します。
ユーザ認証
Transactional Email API は、HTTPリクエストに含まれる api_user, api_key パラメータを使用したユーザ認証を行います。APIユーザの登録方法については、ユーザガイドの「APIユーザ」を参照ください。
権限によるアクセス制御
Transactional Email API は、APIグループ管理者、APIユーザの2つのロール（役割）で利用することができます。また、APIユーザごとに以下のアクセス権限を付与することができます。
| 役割 | 説明 |
|---|---|
| APIグループ管理者 | データの参照・ダウンロード、追加、更新、削除の操作が可能です。 |
| APIユーザ | データの参照・ダウンロードの操作が可能です。 |
| 権限 | 説明 |
|---|---|
| データ参照許可 | メールアドレスを含むデータを参照可能なAPIに対するアクセス権限。 |
| ダウンロード許可 | メールアドレスを含むデータをファイルダウンロード可能なAPIに対するアクセス権限。 |
IPアドレスによるアクセス制御
HTTPリクエストの送信元IPアドレスをチェックし、アクセス制御を行います。アクセス制御の設定方法については、ユーザガイドの「接続IP」を参照ください。
データ暗号化
download アクションによるファイルダウンロードを実行する場合、パスワード付き暗号化ZIP形式でダウンロードするファイルを作成することができます。データ暗号化の設定方法については、ユーザガイドの「Transactional Email API」を参照ください。