Skip to content

Blocks

Blocks provides operations such as searching/referencing, downloading, and canceling the blocked email address when transmission error occurred due to reasons such as the account does not exist.

This API is provided by the management console. For access point host please refer to Common Specifications.

List

Blocks/list provides an operation to search and refer to blocked email addresses.

Request

/transaction/v2/blocks/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.
email No ASCII If this parameter is specified, It will search for a partially matching email address.
start_date No DATE Specifies the search start date (yyyy-mm-dd) to perform a period search,based on the date when the delivery was stopped.The search start date is included in the search period.
restrictions:start_date must be equal to end_date or specify a past date.
end_date No DATE Specifies the search end date (yyyy-mm-dd format) to perform a period search based on the date when the delivery was stopped. The search end date is included in the search period.
removed No BOOLEAN Specifies the true If you want to get the email address that has been blocked.
default:false
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

Response

{
"blocks": [
    {
    "created": "2015-12-14 08:46:00",
    "email": "to1@example.com",
    "id": "cp0ihzuyl3445",
    "occurred": "1",
    "status": "2"
    },
    {
    "created": "2015-12-14 12:19:00",
    "email": "to2@example.com",
    "id": "cp0ihzuyl3479",
    "occurred": "1",
    "status": "2"
    }
    ...
]
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<blocks>
<block>
    <id>cp0ihzuyl3445</id>
    <email>to1@example.com</email>
    <status>2</status>
    <occurred>1</occurred>
    <created>2015-12-14 08:46:00</created>
</block>
<block>
    <id>cp0ihzuyl3479</id>
    <email>to2@example.com</email>
    <status>2</status>
    <occurred>1</occurred>
    <created>2015-12-14 12:19:00</created>
</block>
</blocks>
Property Description
id Data identifier
email Blocked email address (If removed=true, the blocked email address)
status Error status(please refer to here about error status value.)
occurred Number of transmission errors
created Date and time when the delivery was stopped

Error Message

Field Error Code Message (en) Message (ja)
server_composition 10-002 Specified server configuration {0} does not exist. 指定されたサーバ構成 {0} は存在しません。
start_date 10-003 For the start_date please specify a date before the end_date. 開始日には終了日以前の日付を指定してください。
12-002 You do not have the permission to access the specified data. 指定されたデータにアクセスする権限がありません。

Request Example

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=testcomp' https://api.smtps.jp/transaction/v2/blocks/list.json

Download

Blocks/download provides an operation that searches for blocked email addresses and download them in CSV file format.

Request

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

Access Control

Items Value
Roll API group administrator、API user
Authorization Download permisison

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.
email No ASCII If this parameter is specified, It will search for a partially matching email address.
start_date No DATE Specifies the search start date (yyyy-mm-dd) to perform a period search,based on the date when the delivery was stopped.The search start date is included in the search period.
restrictions:start_date must be equal to end_date or specify a past date.
end_date No DATE Specifies the search end date (yyyy-mm-dd format) to perform a period search based on the date when the delivery was stopped. The search end date is included in the search period.
removed No BOOLEAN Specifies the true If you want to get the email address that has been blocked.
default:false

Response

If the request is successful, specify the application/octet-stream in 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

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

File Format

"created","id","email","status","occurred"
"2015-12-14 08:46:00","cp0ihzuyl3445","from1@example.com","2","1"
"2015-12-14 12:19:00","cp0ihzuyl3479","from2@example.com","2","1"
Property Description
created Date and time when the delivery was stopped
id Data identifier
email Email address that is blocked (If removed=true, the blocked email address).
status Error status
occurred Number of transmission errors

Error Message

Field Error Code Message (en) Message (ja)
server_configuration 10-002 Specified server configuration {0} does not exist. 指定されたサーバ構成 {0} は存在しません。
start_date 10-003 For the start_date please specify a date before the end_date. 開始日には終了日以前の日付を指定してください。
12-002 You do not have the permission to access the specified data. 指定されたデータにアクセスする権限がありません。

Request Example

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=testcomp' https://api.smtps.jp/transaction/v2/blocks/download.json > data.zip

Delete

Blocks/delete provides an operation that allows blocked email addresses to be sent permanently.

Allows mail sending to the email address that performed this operation, and controls so that delivery will not be stopped even if the delivery error recurs.

In case is a misjudgment of a delivery error, or you want to be able to send an email address permanently, such as an email address that you must try to send for operation, operate the corresponding email address with this API.

Request

/transaction/v2/blocks/delete.[json|xml]

Access Control

Item Value
Roll API group administrator
Authorization none

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.
email Yes ASCII Specifies the email address to be removed from the blocked list.
restrictions:Search he email address to be deleted by an exact match and ignores the case sensitive.

Response

If the process is successful, the following response message will be displayed.

{
    "message" : "success"
}
<success>
    <message>success</message>
</success>

Error Message

Field Error code Message (en) Message (ja)
server_composition 10-002 Specified server configuration {0} does not exist. 指定されたサーバ構成 {0} は存在しません。
email 12-001 The data specified in the email does not exist. emailで指定されたデータは存在しません。

Request Example

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=testcomp' -d 'email=test@example.com' https://api.smtps.jp/transaction/v2/blocks/delete.json

Cancel

Blocks/cancel provides an operation to cancel an blocked email address. The e-mail address that performed this operation is allowed to send e-mails. However, If the delivery error recurs and the delivery stop condition is met, the delivery is controlled to be stopped.

Please operate the corresponding email address with this API If you want to cancel an blocked e-mail address due to recoverable reasons such as junk e-mail filter settings on the recipient side.

Request

/transaction/v2/blocks/cancel.[json|xml]

Access Control

Item Value
Roll API group administrator
Authorization none

Parameter

Parameter Required Data Type Description
api_user Yes ASCII Specifies the ID used for user authentication.
api_key Yes ASCII pecifies the secret key used for user authentication.
server_composition Yes UTF-8 Specifies the name of the server configuration that will be operated.
email Yes ASCII Specifies the email address to be removed from the blocked list
restrictions: Search he email address to be deleted by an exact match and ignores the case sensitive.

Response

The following response message will be displayed If the process is successful .

{
    "message" : "success"
}
<success>
    <message>success</message>
</success>

Error message

Field Error Code Message (en) Message (ja)
server_composition 10-002 Specified server configuration {0} does not exist. 指定されたサーバ構成 {0} は存在しません。
email 12-001 The data specified in the email does not exist. emailで指定されたデータは存在しません。

Request Example

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'server_composition=testcomp' -d 'email=test@example.com' https://api.smtps.jp/transaction/v2/blocks/cancel.json