Bounces

Bounces は、送信エラーとなったメールアドレスを検索・参照する機能を提供します。このAPIは管理コンソールが提供します。

status

メール送信時にエラーが発生した場合、SMTP応答メッセージまたはバウンスメールを解析し、以下のエラーステータスに分類します。

ステータス	エラー理由	発生原因
1	ホスト不明	DNSによるドメイン解決ができなかった。
2	ユーザ不明	メールアドレスが存在しない。
3	再送タイムアウト	宛先サーバへ接続できない、一時エラー応答が返されたため、再送を行ったが時間内に再送が完了しなかった。
4	受信拒否	宛先サーバのポリシーによりメール受信を拒否された。
5	容量オーバー	メールボックスの容量や、メールサーバのディスク領域の制限を超えたため、宛先サーバがメールを受信できなかった。
6	転送エラー	送信した宛先アドレスと異なるアドレスへのメール送信が失敗した。受信者側の設定で宛先アドレスにメールを保存した後、別アドレスに転送している場合、宛先アドレスにはメールが届いている可能性がある。
7	受信サーバエラー	宛先サーバの設定ミスによりメール送信が失敗した(25番ポートにSMTP認証を設定している、DNSによるドメイン解決を行って接続したにもかかわらず宛先サーバが管理するドメインではないなど）。
8	サイズオーバー	メールサイズが大きすぎるため、宛先サーバが受信を拒否した。
9	アドレス形式エラー	宛先メールアドレスが、メールアドレスの形式に従っていない。
10	配信停止アドレス	過去にユーザ不明等の理由により送信エラーとなったメールアドレスであるため、再度のメール送信を抑止した。
99	その他エラー	宛先サーバが恒久エラーを応答したため、メール送信に失敗した。

list

Bounces/list は、送信エラーとなったメールアドレスを検索・参照する操作を提供します。

リクエスト

/transaction/v1/bounces/list.[json|xml]

アクセス制御

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

パラメータ

パラメータ	必須	データ型	説明
api_user	Yes	ASCII	ユーザ認証に使用するIDを指定します。
api_key	Yes	ASCII	ユーザ認証に使用するシークレットキーを指定します。
server_composition	Yes	UTF-8	操作の対象となるサーバ構成の名称を指定します。
email	No	ASCII	このパラメータで指定された文字列に部分一致するメールアドレスを検索します。
status	No	INTEGER	このパラメータで指定されたエラーステータスに該当するメールアドレスを検索します。
start_date	No	DATE	バウンスメールの受信日を基準とした期間検索を行うために検索開始日(yyyy-mm-dd形式)を指定します。検索開始日は検索期間に含まれます。制約：start_dateはend_dateと等しいか過去日を指定しなければなりません。デフォルト：APIを実行した日
end_date	No	DATE	バウンスメールの受信日を基準とした期間検索を行うために検索終了日(yyyy-mm-dd形式)を指定します。検索終了日は検索期間に含まれます。デフォルト：APIを実行した日
date	No	DATE	バウンスメールの受信日(yyyy-mm-dd形式)を指定します。制約：hour,minute パラメータを指定する場合、本パラメータは必須となります。本パラメータが指定された場合、start_date, end_date への指定値は無視されます。
hour	No	INTEGER	dateで指定された日の1時間分の送信エラーアドレスを検索します。範囲：0-23 制約：未来時刻は指定できません。
minute	No	INTEGER	date, hour で指定された日時の1分間分の送信エラーアドレスを検索します。範囲：0-59 制約：システムデータが確定していない可能性があるため、現在時刻から2分以前の値を指定してください。
p	No	INTEGER	参照するページ位置を指定します。デフォルト：0
r	No	INTEGER	１ページに表示するレコード数を指定します。デフォルト：10

レスポンス

JSONXML

{
"bounces": [
    {
    "from": "from1@example.com",
    "messageId": "\u003C7bedd290-a213-11e5-8344-06ff9846521b@node1\u003E",
    "reason": "host unknown",
    "received": "2015-12-14 12:33:53",
    "status": "1",
    "to": "to1@example.com"
    },
    {
    "from": "from2@example.com",
    "messageId": "\u003dc9633d0-885f-11e5-8329-0638caaed3c7@node1\u003E",
    "reason": "Status:5.1.1 / X-Postfix; unknown user: \"to2@example.com\"",
    "received": "2015-12-14 12:33:53",
    "status": "2",
    "to": "to2@example.com"
    }
    ...
]
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bounces>
<bounce>
    <received>2015-12-14 12:33:53</received>
    <status>1</status>
    <from>from1@example.com</from>
    <to>to1@example.com</to>
    <messageId>&lt;7bedd290-a213-11e5-8344-06ff9846521b@node1&gt;</messageId>
    <reason>host unknown</reason>
</bounce>
<bounce>
    <received>2015-12-14 12:33:53</received>
    <status>2</status>
    <from>from2@example.com</from>
    <to>to2@example.com</to>
    <messageId>&lt;dc9633d0-885f-11e5-8329-0638caaed3c7@node1&gt;</messageId>
    <reason>Status:5.1.1 / X-Postfix; unknown user: "to2@example.com"</reason>
</bounce>
....
</bounces>

プロパティ	説明
received	バウンスメールを受信した日 (YYYY-MM-DD HH:MM:SS形式）
status	エラーステータス
from	メールヘッダのFromに指定されたメールアドレス
to	このメールを送信したメールアドレス
messageId	メールヘッダのMessage-IDフィールドの値
reason	エラーステータスの判定に使用した SMTP応答メッセージまたはバウンスメールの本文

エラーメッセージ

フィールド	エラーコード	メッセージ（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を指定してください。

リクエスト例

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/v1/bounces/list.json

download

Bounces/download は、送信エラーとなったメールアドレスを検索し、CSVファイル形式でダウンロードする操作を提供します。

リクエスト

/transaction/v1/bounces/download.[json|xml]

アクセス制御

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

パラメータ

パラメータ	必須	データ型	説明
api_user	Yes	ASCII	ユーザ認証に使用するIDを指定します。
api_key	Yes	ASCII	ユーザ認証に使用するシークレットキーを指定します。
server_composition	Yes	UTF-8	操作の対象となるサーバ構成の名称を指定します。
email	No	ASCII	このパラメータで指定された文字列に部分一致するメールアドレスを検索します。
status	No	INTEGER	このパラメータで指定されたエラーステータスに該当するメールアドレスを検索します。
start_date	No	DATE	バウンスメールの受信日を基準とした期間検索を行うために検索開始日(yyyy-mm-dd形式)を指定します。検索開始日は検索期間に含まれます。制約：start_dateはend_dateと等しいか過去日を指定しなければなりません。デフォルト：APIを実行した日
end_date	No	DATE	バウンスメールの受信日を基準とした期間検索を行うために検索終了日(yyyy-mm-dd形式)を指定します。検索終了日は検索期間に含まれます。デフォルト：APIを実行した日
date	No	DATE	バウンスメールの受信日(yyyy-mm-dd形式)を指定します。制約：hour,minute パラメータを指定する場合、本パラメータは必須となります。本パラメータが指定された場合、start_date, end_date への指定値は無視されます。
hour	No	INTEGER	dateで指定された日の1時間分の送信エラーアドレスを検索します。範囲：0-23 制約：未来時刻は指定できません。
minute	No	INTEGER	date, hour で指定された日時の1分間分の送信エラーアドレスを検索します。範囲：0-59 制約：システムデータが確定していない可能性があるため、現在時刻から2分以前の値を指定してください。

レスポンス

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

ファイル名

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

ファイルフォーマット

"received","status","from","to","messageId","reason"
"2015-12-14 12:33:53","1","from1@example.com","to1@example.com","<7bedd290-a213-11e5-8344-06ff9846521b@node1>","host unknown"
"2015-12-14 12:33:53","2","from2@example.com","to2@example.com","<dc9633d0-885f-11e5-8329-0638caaed3c7@node1>","Status:5.1.1 / X-ostfix; unknown user: ""to2@example.com"""

プロパティ	説明
received	バウンスメールを受信した日 (YYYY-MM-DD HH:MM:SS形式)
status	エラーステータス
from	メールヘッダのFromに指定されたメールアドレス
to	このメールを送信したメールアドレス
messageId	メールヘッダのMessage-IDフィールドの値
reason	エラーステータスの判定に使用した SMTP応答メッセージまたはバウンスメールの本文

エラーメッセージ

フィールド	エラーコード	メッセージ (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を指定してください。

リクエスト例

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/v1/bounces/download.json > data.zip