Transactional Email API

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


API仕様

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

バージョン1

後方互換のためのバージョンです。

バージョン2

最新の機能を提供するバージョンです。 バージョン1に対して検索キーの追加やHTTPレスポンスで返却するJSONへプロパティの追加などを行っています。


共通仕様

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

項目
プロトコル HTTPS
文字コード UTF-8
改行コード LF

接続先ホストとURL

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

認証

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


HTTPリクエスト

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

メソッド

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

ヘッダ

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

ヘッダフィールド 説明
Accept-Language Transactional Email APIが応答するメッセージの言語タイプを指定します。en または ja のいずれかを指定します。言語指定が無いまたは左記以外の言語を指定された場合、en で動作します。

コンテンツタイプ

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

パラメータ

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

デフォルト値、入力値の範囲などの制限があるパラメータについては、説明欄に以下の書式で記載します。

パラメータ値は文字列として受信し、長さチェックを行います。パラメータ値は最大1024文字 (ASCIIの場合、1024byte, UTF-8の場合、4096byte)まで指定できます。 また、必須パラメータは、最小1文字以上の値を指定する必要があります。


データ型

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 No Content リクエストは正常に処理されたが、対象データが存在しなかった。例えば、メールアドレスを検索キーとして検索処理を実行したが該当するデータが存在しなかった場合、ステータスコード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 などデータ編集を行うリクエストが成功した時に応答します。

JSON

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

XML

<message>User example1@hde.co.jp 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ごとに定義したエラーメッセージを応答することがあります。

コード メッセージ(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}は必須項目です。

セキュリティ

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