SMTP や APIを使用してメールを送信した際に発生するイベントデータを操作することができます。

バージョン

POSTパラメータや応答メッセージのフォーマットはAPIのバージョンによって異なります。利用するバージョンのAPI仕様を参照ください。

現在のバージョンは2です。

バージョン1のAPI仕様はこちらを参照ください。

共通仕様

このセクションでは、Transactional Email API の共通仕様について説明します。

接続先ホストとURL

https://api.smtps.jp/transaction/[version]/[resource]/[action].[format]

• [version]は、APIバージョンを表します。v2 と v1 が指定できます。

• [resource]は、操作対象のリソースを表します。

• [action]は、操作を表します。

• [format]は、レスポンスメッセージのフォーマットを表します。json と xml が指定できます。

認証

Transactional Email API は、HTTPリクエストに含まれる apiuser, apikey パラメータを使用したユーザ認証を行います。APIユーザの登録方法については、ユーザガイドの「APIユーザ」を参照ください。

アクセス制御

各APIで、要求されるAPIユーザのロールが異なります。詳細は、各APIの「アクセス制御」の項目を参照ください。

HTTPリクエスト

このセクションでは、Transactional Email API が受信するHTTPリクエストの仕様について説明します。

HTTPリクエストの取得頻度について

HTTPリクエストの頻度について、日次での取得までは対応可能です。

日次よりも高い頻度での利用を検討されている場合は、サポートセンターまでご相談ください。

メソッド

Transactional Email API は、POSTメソッドのみを受け付けます。

ヘッダ

Transactional Email API は、以下のヘッダフィールドを参照します。

コンテンツタイプ

application/x-www-form-urlencoded または application/json を指定します。

注意

application/json は、バージョン2からサポートしました。
バージョン1では使用できません。

パラメータ

Transactional Email API は全てのHTTPリクエストに、ユーザ認証を行うための api_user, api_key を含める必要があり、かつ、URLごとに定義されたパラメータを送信する必要があります。

このドキュメントは以下フォーマットに従い、パラメータの説明を記述します。

• パラメータ：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 は以下の仕様に従い、データ型を取扱います。

HTTPレスポンス

このセクションでは、Transactional Email APIが送信するHTTPレスポンスの仕様について説明します。

ステータスコード

Transactional Email APIは、以下のステータスコードを応答します。

ヘッダ

Transactional Email APIは、URLで指定されたフォーマットに従い、JSON または、XMLフォーマットのメッセージを応答します。また、download アクションは、ファイルダウンロードを実行します。これらの応答メッセージのフォーマットは、HTTPレスポンスヘッダ Content-Type により判別します。

メッセージ

Transactional Email API は以下のメッセージを応答します。

成功

このメッセージは、add / edit / delete などデータ編集を行うリクエストが成功した時に応答します。

JSON

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

XML

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

エラー

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

JSON

{
    "errors" : [
        {
            "code" : "01-004",
            "field" : "api_user",
            "message" : "api_user is required."
        },
        {
            "code" : "01-004",
            "field" : "api_key",
            "message" : "api_key is required."
        }
    ]
}

XML

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

JSON

{
    "message" : "The process was finished normally but the data was not found."
}

XML

<message>The process was finished normally but the data was not found."</message>

検索結果

list アクションなどの検索操作で対象データが存在した場合、URLごとに定めたフォーマットにてメッセージを応答します。メッセージの詳細については、各APIのマニュアルを参照ください。

エラーメッセージ

Transactional Email APIの共通エラーメッセージを以下に説明します。共通エラーメッセージ以外にも、各APIごとに定義したエラーメッセージを応答することがあります。

セキュリティ

このセクションでは、Transactional Email API のセキュリティについて説明します。

ユーザ認証

Transactional Email API は、HTTPリクエストに含まれる apiuser, apikey パラメータを使用したユーザ認証を行います。APIユーザの登録方法については、ユーザガイドの「APIユーザ」を参照ください。

権限によるアクセス制御

Transactional Email API は、APIグループ管理者、APIユーザの2つのロール（役割）で利用することができます。また、APIユーザごとに以下のアクセス権限を付与することができます。

IPアドレスによるアクセス制御

HTTPリクエストの送信元IPアドレスをチェックし、アクセス制御を行います。アクセス制御の設定方法については、ユーザガイドの「接続IP」を参照ください。

データ暗号化

download アクションによるファイルダウンロードを実行する場合、パスワード付き暗号化ZIP形式でダウンロードするファイルを作成することができます。データ暗号化の設定方法については、ユーザガイドの「Transactional Email API」を参照ください。