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 の例です。

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 などデータ編集を行うリクエストが成功した時に応答します。

JSONXML

{
    "message" : "User example1.hde was deleted"
}

<message>User example1@hennge.com was deleted<message>

エラー

このメッセージは、リクエストが失敗した時に応答します。

JSONXML

{
    "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 と共に以下のメッセージを応答します。

JSONXML

{
    "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} が見つかりませんでした。

セキュリティ

このセクションでは、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」を参照ください。