Skip to content

Deliveries

Deliveries provide a function to search and refer to the status of receive,successfull delivery, delivery error and resend for each email address that has sent.

This API is provided by management console.For access point host please refer to shared specification.

Delivery Status

Following delivery status will be recorded for each mail that has been sent.

Status Description
queued Mail received from the mail relay source server.
succeeded SMTP communication is successfull and mail has sent to destination server.
failed Mail could not be sent to the destination server due to SMTP communication failure.
deferred Mail has resent due to temporary error response from the destination server.

List

Deliveries/list provides an operation to search and refer to the email address and delivery status of sent emails.

Request

/transaction/v2/deliveries/list.[json|xml]

Access Control

Item Value
Roll API group administrator, API user
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 ASCII Searches for the mail address matches to specified delivery status.
date Yes DATE Specifies the search date (yyyy-mm-dd format).
- restrictions: Future date cannot be 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.
p No INTEGER Specifies the page position to refer to.
- default:0
r No INTEGER Specifies the number of records to be displayed on one page.
- default:10
- max: 100
search_option No ASCII Specify this option for an exact match search. See below 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 search_option is not specified, the search will be performed by partial match.
  • 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.

Response

{
"deliveries": [
    {
    "created": "2015-12-14 10:53:52",
    "returnPath": "envelope-from1@example.com",
    "from" : "header-from1@example.com",
    "to": "to1@example.com",
    "messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
    "reason": "",
    "senderIp": "",
    "sourceIp": "10.0.24.10",
    "status": "queued",
    "subject": "sample email #1",
    "apiData" : "CMC00123"
    },
    {
    "created": "2015-12-14 10:53:53",
    "returnPath": "envelope-from1@example.com",
    "from" : "header-from1@example.com",
    "to": "to1@example.com",
    "messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
    "reason": "",
    "sourceIp": "",
    "senderIp": "10.0.24.20",
    "status": "succeeded",
    "subject": "sample email #1",
    "apiData" : "CMC00123"
    },
    ...
]
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveries>
<delivery>
    <created>2015-12-14 10:53:52</created>
    <messageId>&lt;823cb160-a205-11e5-833e-06ff9846521b@node1&gt;</messageId>
    <status>queued</status>
    <sourceIp>10.0.24.10</sourceIp>
    <senderIp></senderIp>
    <returnPath>envelope-from1@example.com</returnPath>
    <from>header-from1@example.com</from>
    <to>to1@example.com</to>
    <subject>sample email #1</subject>
    <reason></reason>
    <apiData>CMC00123</apiData>
</delivery>
<delivery>
    <created>2015-12-14 10:53:53</created>
    <messageId>&lt;823cb160-a205-11e5-833e-06ff9846521b@node1&gt;</messageId>
    <status>succeeded</status>
    <sourceIp></sourceIp>
    <senderIp>10.0.24.20</senderIp>
    <returnPath>envelope-from1@example.com</returnPath>
    <from>header-from1@example.com</from>
    <to>to1@example.com</to>
    <subject>sample email #1</subject>
    <reason></reason>
    <apiData>CMC00123</apiData>
</delivery>
....
</deliveries>
Property Description
created Date and time the delivery status for the email address was recorded (YYYY-MM-DD HH:mm:ss format).
messageId The value of the Message-ID field in the email header.
status Delivery status
sourceIp The connection IP of the mail relay source server.Recorded If the delivery status is queued.
senderIp IP used when sending this mail to the destination server.Recorded If the delivery status is other than queued.
returnPath Envelope from address used when sending the email.
from Header from address of this email.
to Envelope to address used when sending the email.
subject Subject of the maail.
reason SMTP response message.Recorded If the delivery status is failed or deferred.
apiData The header value of X-Api-Data given by the email sender application.

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/deliveries/list.json

Download

Deliveries/download provides an operation that searches for the email address and delivery status of the email you sent and download them in CSV file format.

Request

/transaction/v2/deliveries/download.[json|xml]

Access Control

Item Value
Roll 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 '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 ASCII Searches for the mail address matches to specified delivery status.
date Yes DATE Specifies the search date (yyyy-mm-dd format).
- restrictions: Future date cannot be 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. Please refer to list action parameters for more details.

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

deliveries-yyyyMMdd_HHmmss.zip (example: deliveries-20151207_175202.zip)

File Format

"created","messageId","status","sourceIp","senderIp","returnPath","from","to","subject","apiData","reason"
"2015-12-14 10:53:52","<823cb160-a205-11e5-833e-06ff9846521b@node1>","queued","10.0.24.10","","envelope-from1@example.com","header-from1@example.com","to1@example.com,"sample email #1","CMC00123",""
"2015-12-14 10:53:53","<823cb160-a205-11e5-833e-06ff9846521b@node1>","succeeded","","10.0.24.20","envelope-from1@example.com","header-from1@example.com","to1@example.com","sample email #1","CMC00123",""
Property Description
created Date and time the delivery status for the email address was recorded (YYYY-MM-DD HH:mm:ss format).
messageId The value of the Message-ID field in the email header.
status Delivery status
sourceIp The connection IP of the mail relay source server.Recorded If the delivery status is queued.
senderIp IP used when sending this mail to the destination server.Recorded If the delivery status is other than queued.
returnPath Envelope from address used when sending the email.
from Header from address of this email.
to Envelope to address used when sending the email.
subject Subject of the mail.
apiData The header value of X-Api-Data given by the email sender application.
reason SMTP response message.Recorded If the delivery status is failed or deferred.

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/deliveries/download.json > data.zip