Skip to content

Bounces

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

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

エラーステータス

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

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

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

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

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

レスポンス

{
"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