Deliveries

Deliveries は、送信したメールアドレス1通ごとの受信、送信成功、送信エラー、再送等のステータスを検索・参照する機能を提供します。

このAPIは管理コンソールが提供します。接続先ホストについては共通仕様を参照ください。

配信ステータス

送信したメール1通ごとに、以下の配信ステータスを記録します。

ステータス	説明
queued	メールリレー元サーバーからメールを受信した。
succeeded	SMTP通信が成功し、宛先サーバーにメールが送信できた。
failed	SMTP通信が失敗し、宛先サーバーにメールが送信できなかった。
deferred	宛先サーバーから一時エラー応答があったため、メールを再送している。

list

Deliveries/list は、送信したメールのメールアドレスと配信ステータスを、検索・参照する操作を提供します。

リクエスト

/transaction/v2/deliveries/list.[json|xml]

アクセス制御

項目	値
ロール	APIグループ管理者、APIユーザ
権限	データ参照許可

パラメータ

パラメータ	必須	データ型	説明
api_user	Yes	ASCII	ユーザ認証に使用するIDを指定します。
api_key	Yes	ASCII	ユーザ認証に使用するシークレットキーを指定します。
server_composition	Yes	UTF-8	操作の対象となるサーバ構成の名称を指定します。
from	No	ASCII	指定された文字列にFromアドレスが部分一致するデータを検索します。
to	No	ASCII	指定された文字列にToアドレスが部分一致するデータを検索します。
api_data	No	ASCII	指定された文字列にX-Api-Dataのヘッダ値が部分一致するデータを検索します。
status	No	ASCII	指定された配信ステータスに該当するメールアドレスを検索します。
date	Yes	DATE	検索対象日(yyyy-mm-dd形式)を指定します。制約：未来日付は指定できません。
hour	No	INTEGER	dateで指定された日の1時間分の配信ステータスとメールアドレスを検索します。範囲：0-23 制約：未来時刻は指定できません。
minute	No	INTEGER	date, hour で指定された日時の1分間分の配信ステータスとメールアドレスを検索します。範囲：0-59 制約：システムデータが確定していない可能性があるため、現在時刻から2分以前の値を指定してください。
p	No	INTEGER	参照するページ位置を指定します。デフォルト：0
r	No	INTEGER	1ページに表示するレコード数を指定します。デフォルト：10 最大取得件数：100
search_option	No	ASCII	完全一致検索を行う場合、このオプションを指定します。詳細は後述を参照ください。
attachment_info	No	BOOLEAN	true：attachments, mailSize, virusCheckedの項目を出力します。 false：attachments, mailSize, virusCheckedの項目を出力しません。デフォルト：false

検索オプション

以下のJSONで検索オプションを指定します。

JSON

{
    "from" : "full",
    "to" : "full",
    "api_data" : "full"
}

from, to, api_data は検索オプションをどのパラメータに適用するかを指定します。検索方法を変更したいパラメータのみを指定してください。search_option の指定が無い場合は、部分一致で検索します。

値に "full" を指定した場合、完全一致での検索を行います。
値に "part" を指定した場合、部分一致での検索を行います。

レスポンス

JSONXML

{
"deliveries": [
    {
    "created": "2015-12-14 10:53:52",
    "returnPath": "envelope-from1@example.com",
    "from" : "header-from1@example.com",
    "to": "to1@example.com",
    "messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
    "reason": "",
    "senderIp": "",
    "sourceIp": "10.0.24.10",
    "status": "queued",
    "subject": "sample email #1",
    "apiData" : "CMC00123",
    "attachments" : "0",
    "mailSize" : "123456",
    "virusChecked" : "true"

    },
    {
    "created": "2015-12-14 10:53:53",
    "returnPath": "envelope-from1@example.com",
    "from" : "header-from1@example.com",
    "to": "to1@example.com",
    "messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
    "reason": "",
    "sourceIp": "",
    "senderIp": "10.0.24.20",
    "status": "succeeded",
    "subject": "sample email #1",
    "apiData" : "CMC00123",
    "attachments" : "0",
    "mailSize" : "123456",
    "virusChecked" : "true"

    },
    ...
]
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveries>
<delivery>
    <created>2015-12-14 10:53:52</created>
    <messageId>&lt;823cb160-a205-11e5-833e-06ff9846521b@node1&gt;</messageId>
    <status>queued</status>
    <sourceIp>10.0.24.10</sourceIp>
    <senderIp></senderIp>
    <returnPath>envelope-from1@example.com</returnPath>
    <from>header-from1@example.com</from>
    <to>to1@example.com</to>
    <subject>sample email #1</subject>
    <reason></reason>
    <apiData>CMC00123</apiData>
    <attachments>0</attachments>
    <mailSize>123456</mailSize>
    <virusChecked>true</virusChecked>

</delivery>
<delivery>
    <created>2015-12-14 10:53:53</created>
    <messageId>&lt;823cb160-a205-11e5-833e-06ff9846521b@node1&gt;</messageId>
    <status>succeeded</status>
    <sourceIp></sourceIp>
    <senderIp>10.0.24.20</senderIp>
    <returnPath>envelope-from1@example.com</returnPath>
    <from>header-from1@example.com</from>
    <to>to1@example.com</to>
    <subject>sample email #1</subject>
    <reason></reason>
    <apiData>CMC00123</apiData>
    <attachments>0</attachments>
    <mailSize>123456</mailSize>
    <virusChecked>true</virusChecked>

</delivery>
....
</deliveries>

プロパティ	説明
created	メールアドレスに対する配信ステータスを記録した日時 (YYYY-MM-DD HH:mm:ss形式)
messageId	メールヘッダのMessage-IDフィールドの値
status	配信ステータス
sourceIp	メールリレー元サーバーの接続IP。配信ステータスが queued である場合に記録されます。
senderIp	このメールを宛先サーバーに送信した時に使用したIP。配信ステータスが queued 以外である場合に記録されます。
returnPath	メールを送信するときに使用したエンベロープ Fromアドレス。
from	このメールのヘッダFromアドレス。
to	メールを送信するときに使用したエンベロープ Toアドレス。
subject	メールの件名。
reason	SMTPの応答メッセージ。配信ステータスが failed または deferred である場合に記録されます。
apiData	メール送信元アプリケーションが付与した X-Api-Data のヘッダ値。
attachments	添付ファイル数。
mailSize	メールを受信した際のサイズ(Byte)。
virusChecked	ウイルスチェック実施有無。実施：true 未実施：false

エラーメッセージ

フィールド	エラーコード	メッセージ (en)	メッセージ (ja)
server_composition	10-002	Specified server composition, {0}, was not found.	指定されたサーバ構成 {0} は存在しません。
status	13-001	The specified {0} status is not defined.	指定されたステータス {0} は定義されていません。
date	13-002	Future date cannot be specified.	将来の日付は指定できません。
hour	13-003	Future time cannot be specified.	将来の時刻は指定できません。
minute	13-004	Please specify the time less than 2 minutes or equal to the current time.	現在時刻から2分以前を指定してください。
minute	13-005	Please specify the hour when using the minute.	minuteを使用する場合、hourを指定してください。
search_option	13-006	Please specify from, to, api_data for search option properties.	検索オプションのプロパティには、from, to, api_data のいずれかを指定してください。
search_option	13-007	Please specify either full or part as the search option value.	検索オプションの値には、full, part のいずれかを指定してください。

リクエスト例

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=sandbox' -d 'date=2020-01-01' https://api.smtps.jp/transaction/v2/deliveries/list.json

download

Deliveries/download は、送信したメールのメールアドレスと配信ステータスを検索し、CSVファイル形式でダウンロードする操作を提供します。

リクエスト

/transaction/v2/deliveries/download.[json|xml]

アクセス制御

項目	値
ロール	APIグループ管理者、APIユーザ
権限	ダウンロード許可

パラメータ

パラメータ	必須	データ型	説明
api_user	Yes	ASCII	ユーザ認証に使用するIDを指定します。
api_key	Yes	ASCII	ユーザ認証に使用するシークレットキーを指定します。
server_composition	Yes	UTF-8	操作の対象となるサーバ構成の名称を指定します。
from	No	ASCII	指定された文字列にFromアドレスが部分一致するデータを検索します。
to	No	ASCII	指定された文字列にToアドレスが部分一致するデータを検索します。
api_data	No	ASCII	指定された文字列にX-Api-Dataのヘッダ値が部分一致するデータを検索します。
status	No	ASCII	指定された配信ステータスに該当するメールアドレスを検索します。
date	Yes	DATE	検索対象日(yyyy-mm-dd形式)を指定します。制約：未来日付は指定できません。
hour	No	INTEGER	dateで指定された日の1時間分の配信ステータスとメールアドレスを検索します。範囲：0-23 制約：未来時刻は指定できません。
minute	No	INTEGER	date, hour で指定された日時の1分間分の配信ステータスとメールアドレスを検索します。範囲：0-59 制約：システムデータが確定していない可能性があるため、現在時刻から2分以前の値を指定してください。
search_option	No	ASCII	完全一致検索を行う場合、このオプションを指定します。詳細は listアクションのパラメータ説明を参照ください。
attachment_info	No	BOOLEAN	true：attachments, mailSize, virusCheckedの項目を出力します。 false：attachments, mailSize, virusCheckedの項目を出力しません。デフォルト：false

レスポンス

リクエストが成功した場合、Content-Type に application/octet-stream を指定し、以下フォーマットのCSVファイルをZIP圧縮してダウンロードします。データ暗号化を設定している場合、パスワード付き暗号化ZIPファイルをダウンロードします。

ファイル名

deliveries-yyyyMMdd_HHmmss.zip　(例: deliveries-20151207_175202.zip)

ファイルフォーマット

"created","messageId","status","sourceIp","senderIp","returnPath","from","to","subject","apiData","reason","attachments","mailSize",“virusChecked"
"2015-12-14 10:53:52","<823cb160-a205-11e5-833e-06ff9846521b@node1>","queued","10.0.24.10","","envelope-from1@example.com","header-from1@example.com","to1@example.com,"sample email #1","CMC00123","","0","123456",“true"
"2015-12-14 10:53:53","<823cb160-a205-11e5-833e-06ff9846521b@node1>","succeeded","","10.0.24.20","envelope-from1@example.com","header-from1@example.com","to1@example.com","sample email #1","CMC00123","","0","123456",“true"

プロパティ	説明
messageId	メールヘッダのMessage-IDフィールドの値
status	配信ステータス
sourceIp	メールリレー元サーバーの接続IP。配信ステータスが queued である場合に記録されます。
senderIp	このメールを宛先サーバーに送信した時に使用したIP。配信ステータスが queued 以外である場合に記録されます。
returnPath	メールを送信するときに使用したエンベロープ Fromアドレス。
from	このメールのヘッダFromアドレス。
to	メールを送信するときに使用したエンベロープ Toアドレス。
subject	メールの件名。
apiData	メール送信元アプリケーションが付与した X-Api-Data のヘッダ値。
reason	SMTPの応答メッセージ。配信ステータスが failed または deferred である場合に記録されます。
attachments	添付ファイル数。
mailSize	メールを受信した際のサイズ(Byte)。
virusChecked	ウイルスチェック実施有無。実施：true 未実施：false

エラーメッセージ

フィールド	エラーコード	メッセージ (en)	メッセージ (ja)
server_composition	10-002	Specified server composition, {0}, was not found.	指定されたサーバ構成 {0} は存在しません。
status	13-001	The specified {0} status is not defined.	指定されたステータス {0} は定義されていません。
date	13-002	Future date cannot be specified.	将来の日付は指定できません。
hour	13-003	Future time cannot be specified.	将来の時刻は指定できません。
minute	13-004	Please specify the time less than 2 minutes or equal to the current time.	現在時刻から2分以前を指定してください。
minute	13-005	Please specify the hour when using the minute.	minuteを使用する場合、hourを指定してください。
search_option	13-006	Please specify from, to, api_data for search option properties.	検索オプションのプロパティには、from, to, api_data のいずれかを指定してください。
search_option	13-007	Please specify either full or part as the search option value.	検索オプションの値には、full, part のいずれかを指定してください。

リクエスト例

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=sandbox' -d 'date=2020-01-01' https://api.smtps.jp/transaction/v2/deliveries/download.json > data.zip