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
search_option No ASCII 完全一致検索を行う場合、このオプションを指定します。詳細は後述を参照ください。

検索オプション

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

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

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

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

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



レスポンス

JSON

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

<?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フィールドの値
reason エラーステータスの判定に使用した SMTP応答メッセージまたはバウンスメールの本文
returnPath メール送信時に使用したエンベローブFrom
subject エラーとなったメールの件名
apiData メール送信元アプリケーションが付与した X-Api-Data のヘッダ値

エラーメッセージ

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

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フィールドの値
reason エラーステータスの判定に使用した SMTP応答メッセージまたはバウンスメールの本文
returnPath メール送信時に使用したエンベローブFrom
subject エラーとなったメールの件名
apiData メール送信元アプリケーションが付与した X-Api-Data のヘッダ値

エラーメッセージ

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