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
Role	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.

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

JSONXML

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