Bounces
Bounces provides a function that search and refer the email address that caused a transmission error.
This API provided by management console. For access point host please refer to shared specification.
Error Status
Analyze the SMTP response messages or bounce emails and categorize in the following error status.
| Error status | Error reaason | source of trouble |
|---|---|---|
| 1 | Unknown host | Domain resolution by DNS could not be done. |
| 2 | Unknown user | Mail address does not exist. |
| 3 | Retransmission timeout | Unable to connect to the destination server.A temporary error response was returned and resending was performed but could not completed in time. |
| 4 | Rejection | Email reception was rejected due to destinations server's policy. |
| 5 | Overcapacity | The destination server could not receive the mail due to exceeded disk space limit of the mail server or mailbox capacity . |
| 6 | Forward error | Failed to send an email to a different address from the destination address you sent.When the mail is saved in the destination address in the recipient's settings and forwarded to another address, the mail have arrive at the destination address. |
| 7 | Receiving server error | Unable to send due to a setting error on the destination server. The following are possible reason. - SMTP authentication is set on port 25. - It is not a domain managed by the destination server even though the domain is resolved by DNS and connected. |
| 8 | Oversized | Receiving was rejected by the destination server because the email size is too large. |
| 9 | Address format error | The destination email address does not follow the email address format. |
| 10 | Blocked address | Email transmission was restrained since It is an e-mail address that caused a transmission error in the past due to reasons such as unknown user. |
| 99 | Others | Transmission was failed because the destination server responded with a permanent error. |
List
Bounces/list provides an operation to search and refer to email address that caused the transmission error.
Request
/transaction/v2/bounces/list.[json|xml]
Access Control
| Item | Value |
|---|---|
| Role | API group administrator, APIuser |
| Authorization | Data reference permission |
Parameter
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| api_user | Yes | ASCII | Specifies the ID used for user authentication. |
| api_key | Yes | ASCII | Specifies the secret key used for user authentication. |
| server_composition | Yes | UTF-8 | Specifies the name of the server configuration that will be operated. |
| from | No | ASCII | Searches for the data that partially matches the 'from address' in the specified character strings. |
| to | No | ASCII | Searches for the data that partially matches 'to address' in the specified character string. |
| api_data | No | ASCII | Searches for the data that partially matches 'header value of X-Api-Data' in the specified character string. |
| status | No | INTEGER | Searches for the data that relevant to specified error status. |
| start_date | No | DATE | Specifies the search start date (yyyy-mm-dd format) to perform a period search based on the received date of the bounce email.The search start date is included in the search period. - restrictions: start_date must be equal to end_date or specify a past date. - default: The date that API was implemented. |
| end_date | No | DATE | Specifies the search end date (yyyy-mm-dd format) to perform a period search based on the received date of the bounce email.The search end date is included in the search period. - default: The date that API was implemented. |
| date | No | DATE | Specifies the received date of the bounce mail (yyyy-mm-dd format). - restrictions: This parameter is required when the hour and minute parameters are specified.The values specified for start_date and end_date will be ignored If this parameter is specified. |
| hour | No | INTEGER | Searches for one hour's worth of transmission error addresses on the day specified by date. - span:0-23 - restrictions: Future time cannot be specified. |
| minute | No | INTEGER | Searches for one minute's worth of transmission error addresses on the date and time specified by date and hour. - span: 0-59 - restrictions: Please specify a value 2 minutes before the current time since the system data may not be settled. |
| p | No | INTEGER | Specifies the page position to refer. - default: 0 |
| r | No | INTEGER | Specifies the number of records that will be displayed on one page - default: 10 - max: 100 |
| search_option | No | ASCII | Specify this option for an exact match search.Please see the following for details. |
Search option
Specifies the search option in the following JSON.
{
"from" : "full",
"to" : "full",
"api_data" : "full"
}
from, to, and api_data specify which parameter the search option applies to.
Specify only the parameters that you want to change the search method.
- If "full" is specified as the value, the search will be performed with an exact match.
- If "part" is specified as the value, the search will be performed by partial match. match.
Response
{
"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" : "Notification about service",
"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" : "Notification about service",
"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><7bedd290-a213-11e5-8344-06ff9846521b@node1></messageId>
<reason>host unknown</reason>
<returnPath>env-from1@example.com</returnPath>
<subject>Notification about service</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><dc9633d0-885f-11e5-8329-0638caaed3c7@node1></messageId>
<reason>Status:5.1.1 / X-Postfix; unknown user: "to2@example.com"</reason>
<returnPath>env-from2@example.com</returnPath>
<subject>Notification about service</subject>
<apiData>CMC00124</apiData>
</bounce>
....
</bounces>
| Property | Description |
|---|---|
| created | The date that bounce mail was received (YYYY-MM-DD HH:MM:SS format) |
| status | Error status |
| from | The mail address that specified in the 'from' of the mail header |
| to | Email address that send this mail |
| messageId | Message-ID field value of the mail header |
| returnPath | Envelope-From used during sending a from email |
| subject | The 'subject field' of the email in which the error occured |
| apiData | X-Api-Data header value given by the mail source application |
| reason | The body of the bounce email or SMTP response message used to determine the error status |
Error Message
| Field | Error code | Message (en) | Message (ja) |
|---|---|---|---|
| server_composition | 10-002 | Specified server configuration {0} does not exist. | 指定されたサーバ構成 {0} は存在しません。 |
| status | 13-001 | The specified {0} status is undefined. | 指定されたステータス {0} は定義されていません。 |
| date | 13-002 | Future date cannot be specified. | 将来の日付は指定できません。 |
| hour | 13-003 | Future time cannot be specified. | 将来の時刻は指定できません。 |
| minute | 13-004 | Please specify the time 2 minutes before the current time. | 現在時刻から2分以前を指定してください。 |
| minute | 13-005 | Please specify the 'hour' when using the 'minute'. | minuteを使用する場合、hourを指定してください。 |
| search_option | 13-006 | Please specify either 'from', 'to', or 'api_data' as search option properties. | 検索オプションのプロパティには、from, to, api_data のいずれかを指定してください。 |
| search_option | 13-007 | Please specify either 'full' or 'part' as the search option value. | 検索オプションの値には、full, part のいずれかを指定してください。 |
Request Example
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 provides an operation that searches for the mail address with the delivery error and download them in CSV file format.
Request
/transaction/v2/bounces/download.[json|xml]
Access Control
| Item | Value |
|---|---|
| Role | API group administrator, API user |
| Authorization | Download permission |
Parameter
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| api_user | Yes | ASCII | Specifies the ID used for user authentication. |
| api_key | Yes | ASCII | Specifies the secret key used for user authentication. |
| server_composition | Yes | UTF-8 | Specifies the name of the server configuration that will be operated. |
| from | No | ASCII | Searches for the data that partially matches the 'from address' in the specified character strings. |
| to | No | ASCII | Searches for the data that partially matches the 'to address' in the specified character strings. |
| api_data | No | ASCII | Searches for the data that partially matches the 'header value of X-Api-Data' in the specified character strings. |
| status | No | INTEGER | Searches for the data that relevant to specified error status. |
| start_date | No | DATE | Specifies the search start date (yyyy-mm-dd format) to perform a period search based on the received date of the bounce email. The search start date is included in the search period. - restrictions: start_date must be equal to end_date or specify a past date. - default: The date that API was implemented. |
| end_date | No | DATE | Specifies the search end date (yyyy-mm-dd format) to perform a period search based on the received date of the bounce email.The search end date is included in the search period. - default: The date that API was implemented. |
| date | No | DATE | Specifies the received date of the bounce mail.(yyyy-mm-dd format). - restrictions: This parameter is required when the hour and minute parameters are specified. The values specified for start_date and end_date will be ignored If this parameter is specified. |
| hour | No | INTEGER | Searches for one hour's worth of delivery error and mail addresses on the day specified by date. - span: 0-23 - restrictions: Future time cannot be specified. |
| minute | No | INTEGER | Searches for one minute's worth of delivery error and mail addresses on the date and time specified by date and hour. - span: 0-59 - restrictions: Please specify a value 2 minutes before the current time since the system data may not be settled. |
| search_option | No | ASCII | Specify this option for an exact match search. For more information please refer to list action parameter description. |
Response
If the request is successful, specify the application/octet-stream to Content-Type and download the ZIP-compress CSV file in the following format.
Download the password-protected encrypted ZIP file If you have set data encryption.
File Name
bounces-yyyyMMdd_HHmmss.zip (example: bounces-20151207_175202.zip)
File Format
"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","notification about the service","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","notification about the service","CMC00124","Status:5.1.1 / X-ostfix; unknown user: ""to2@example.com"""
| Property | Description |
|---|---|
| created | The date that bounce mail was received (YYYY-MM-DD HH:mm:ss format) |
| status | error status |
| from | The mail address that specified in the 'from' of the mail header |
| to | Email address that send this mail |
| messageId | Message-ID field value of the mail header |
| returnPath | Envelope-From used during sending a from email |
| subject | The 'subject field' of the email in which the error occured |
| apiData | X-Api-Data header value given by the mail source application |
| reason | The body of the bounce email or SMTP response message used to determine the error status |
Error Message
| Field | Error code | Message (en) | Message (ja) |
|---|---|---|---|
| server_composition | 10-002 | Specified server configuration {0} does not exist. | 指定されたサーバ構成 {0} は存在しません。 |
| status | 13-001 | The specified {0} status is undefined. | 指定されたステータス {0} は定義されていません。 |
| date | 13-002 | Future date cannot be specified. | 将来の日付は指定できません。 |
| hour | 13-003 | Future time cannot be specified. | 将来の時刻は指定できません。 |
| minute | 13-004 | Please specify the time 2 minutes before the current time. | 現在時刻から2分以前を指定してください。 |
| minute | 13-005 | Please specify the 'hour' when using the 'minute'. | minuteを使用する場合、hourを指定してください。 |
| search_option | 13-006 | Please specify either 'from', 'to', or 'api_data' as search option properties. | 検索オプションのプロパティには、from, to, api_data のいずれかを指定してください。 |
| search_option | 13-007 | Please specify either 'full' or 'part' as the search option value. | 検索オプションの値には、full, part のいずれかを指定してください。 |
Request Example
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