Skip to content

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.
11 Unsubscribed address Suppressed emails sending with the One-click Unsubscrbe function.
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>&lt;7bedd290-a213-11e5-8344-06ff9846521b@node1&gt;</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>&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>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