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). |
hour | No | INTEGER | Searches for one hour's worth of delivery error and mail addresses on the day specified by 'date'. |
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'. |
p | No | INTEGER | Specifies the page position to refer to. |
r | No | INTEGER | Specifies the number of records to be displayed on one page. |
search_option | No | ASCII | Specify this option for an exact match search. See below for details. |
attachment_info | No | BOOLEAN | true：attachments, mailSize, virusChecked will be displayed. |
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_optionis 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
JSON
{
"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",
"attachments" : "0",
"mailSize" : "123456",
"virusChecked" : "true"
},
{
"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",
"attachments" : "0",
"mailSize" : "123456",
"virusChecked" : "true"
},
...
]
}
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. |
attachments | Number of attachment files. |
mailSize | Email size at the time of receipt (bytes) |
virusChecked | Virus scan performed or not. |
XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveries>
<delivery>
<created>2015-12-14 10:53:52</created>
<messageId><823cb160-a205-11e5-833e-06ff9846521b@node1></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>
<attachments>0</attachments>
<mailSize>123456</mailSize>
<virusChecked>true</virusChecked>
</delivery>
<delivery>
<created>2015-12-14 10:53:53</created>
<messageId><823cb160-a205-11e5-833e-06ff9846521b@node1></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>
<attachments>0</attachments>
<mailSize>123456</mailSize>
<virusChecked>true</virusChecked>
</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. |
attachments | Number of attachment files. |
mailSize | Email size at the time of receipt (bytes) |
virusChecked | Virus scan performed or not. |
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.jsonDownload
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). |
hour | No | INTEGER | Searches for one hour's worth of delivery error and mail addresses on the day specified by 'date'. |
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'. |
search_option | No | ASCII | Specify this option for an exact match search. Please refer to list action parameters for more details. |
attachment_info | No | BOOLEAN | true：attachments, mailSize, virusChecked will be displayed. |
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","attachments","mailSize","virusChecked"
"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","","0","123456","true"
"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","","0","123456","true"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. |
attachments | Number of attachment files. |
mailSize | Email size at the time of receipt (bytes) |
virusChecked | Virus scan performed or not. |
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