Bounces

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

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

エラーステータス

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

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

list

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

リクエスト

/transaction/v2/bounces/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	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	1ページに表示するレコード数を指定します。デフォルト：10 最大取得件数：100
search_option	No	ASCII	完全一致検索を行う場合、このオプションを指定します。詳細は後述を参照ください。

検索オプション

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

JSON

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

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

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

レスポンス

JSONXML

{
"bounces": [
    {
    "from": "from1@example.com",
    "messageId": "\u003C7bedd290-a213-11e5-8344-06ff9846521b@node1\u003E",
    "reason": "host unknown",
    "created": "2015-12-14 12:33:53",
    "status": "1",
    "to": "to1@example.com",
    "returnPath" : "env-from1@example.com",
    "subject" : "サービスに関するお知らせ",
    "apiData" : "CMC00123"
    },
    {
    "from": "from2@example.com",
    "messageId": "\u003dc9633d0-885f-11e5-8329-0638caaed3c7@node1\u003E",
    "reason": "Status:5.1.1 / X-Postfix; unknown user: \"to2@example.com\"",
    "created": "2015-12-14 12:33:53",
    "status": "2",
    "to": "to2@example.com",
    "returnPath" : "env-from2@example.com",
    "subject" : "サービスに関するお知らせ",
    "apiData" : "CMC00124"
    }
    ...
]
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bounces>
<bounce>
    <created>2015-12-14 12:33:53</created>
    <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>
    <returnPath>env-from1@example.com</returnPath>
    <subject>サービスに関するお知らせ</subject>
    <apiData>CMC00123</apiData>
</bounce>
<bounce>
    <created>2015-12-14 12:33:53</created>
    <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>
    <returnPath>env-from2@example.com</returnPath>
    <subject>サービスに関するお知らせ</subject>
    <apiData>CMC00124</apiData>
</bounce>
....
</bounces>

プロパティ	説明
created	バウンスメールを受信した日 (YYYY-MM-DD HH:MM:SS形式）
status	エラーステータス
from	メールヘッダのFromに指定されたメールアドレス
to	このメールを送信したメールアドレス
messageId	メールヘッダのMessage-IDフィールドの値
returnPath	メール送信時に使用したエンベローブFrom
subject	エラーとなったメールの件名
apiData	メール送信元アプリケーションが付与した X-Api-Data のヘッダ値
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を指定してください。
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/bounces/list.json

download

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

リクエスト

/transaction/v2/bounces/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	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分以前の値を指定してください。
search_option	No	ASCII	完全一致検索を行う場合、このオプションを指定します。詳細は listアクションのパラメータ説明を参照ください。

レスポンス

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

ファイル名

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

ファイルフォーマット

"created","status","from","to","messageId","returnPath","subject","apiData","reason"
"2015-12-14 12:33:53","1","from1@example.com","to1@example.com","<7bedd290-a213-11e5-8344-06ff9846521b@node1>","env-from1@example.com","サービスに関するお知らせ","CMC00123","host unknown"
"2015-12-14 12:33:53","2","from2@example.com","to2@example.com","<dc9633d0-885f-11e5-8329-0638caaed3c7@node1>","env-from2@example.com","サービスに関するお知らせ","CMC00124","Status:5.1.1 / X-ostfix; unknown user: ""to2@example.com"""

プロパティ	説明
created	バウンスメールを受信した日 (YYYY-MM-DD HH:MM:SS形式）
status	エラーステータス
from	メールヘッダのFromに指定されたメールアドレス
to	このメールを送信したメールアドレス
messageId	メールヘッダのMessage-IDフィールドの値
returnPath	メール送信時に使用したエンベローブFrom
subject	エラーとなったメールの件名
apiData	メール送信元アプリケーションが付与した X-Api-Data のヘッダ値
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を指定してください。
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/bounces/download.json > data.zip