Skip to content

Transactional Email API

You can operate the event data that occurs when sending an email using SMTP or API.


The format of POST parameters and response messages differs depending on the API version. Please refer to the API specifications of the version you use.

Current version is 2.

Common Specification

Common specification of the Transactional Email API will be explained in this section.

Item Value
Protocol HTTPS
Character code UTF-8
Newline code LF

Access Point Host and URL[version]/[resource]/[action].[format]
  • [version] represents the API version. You can specify v2.
  • [resource] represents the resource of the operation.
  • [action] represents the operation.
  • [format] represents the format of the response message. You can specify json and xml.


The Transactional Email API perform a user authentication that uses the api_user and api_key parameters included in the HTTP request. For APU user registration please refer to "API user" in user guide.

Access Control

Each API requires a different role for the API user. For more information about each API,please refer to "access control" item.

HTTP Request

HTTP request specifications received by the Transactional Email API will be explained in this section.

Recommended request frequency

We recommend using this API request at most once a day.

If you are considering more frequent use, please contact our support center.


The Transactional Email API only accepts POST methods.

Transactional Email API references the following header fields:

Header Field Description
Accept-Language Specifies the language type of the message that the Transactional Email API responds to. Specifies either en or ja.If no language is specified or a language other than the ones on the left is specified, 'en' will work.

Content Type

Specifies application/x-www-form-urlencoded or application/json.


The Transactional Email API must include api_user, api_key, for user authentication in all HTTP requests and must send the parameters defined for each URL.

This document describes the parameters according to the following format.

Parameter Required Data Type Description
api_user Yes ASCII ID used for user authentication.
api_key Yes ASCII secret key used for user authentication.
server_composition Yes UTF-8 name of the server configuration that will be operated (Please refer to here) for server configuration
p No INTEGER Page position of the onbtained data
r No INTEGER Number of records of data that will be acquired.
  • Parameter:The name of the parameter to POST.
  • Required:If this parameter is required,Yes.
  • Data Type:Data type of the parameter value.(Refer to below Data Type
  • Description:Description about this parameter.

For parameters with restrictions such as default value and input value range, input in the following format in the description column.

  • Default:(default value)
  • Span:min=(minimum value) / max=(maximum value)
  • Restrictions:Description about the restrictions on parameters. For example, 'start_date' must be equal to 'end_date' or a past date.

The parameter value is received as a character string and the length is checked. The parameter value can be specified up to 1024 characters (1024 bytes for ASCII, 4096 bytes for UTF-8). The required parameter must specify a value of at least one character.

When specifying application/x-www-form-urlencoded

Create the parameter name and the value set and then POST.

When specifying application/json

Create a JSON with the parameter name as property and POST it.

The following is a JSON example that API Deliveries/list calls.

"api_user" : "",
"api_key" : "a29yZWhhcGFzc3dvcmRkZXN1",
"server_composition" : "sandbox",
"to" : "",
"status" : "failed",
"search_option" : {
    "to" : "part",
    "from" : "full",
    "api_data" : "full"

Data Type

Transactional Email API handles data types according to the following specifications.

Data Type Description
UTF-8 Represents multibyte characters, including ASCII.
ASCII Represents printable ASCII characters.
INTEGER Represents a number in the range -2147483648 to 2147483647.
DATE Represents a date in YYYY-MM-DD format. If DD = 99, it is interpreted as the last day of the specified month.
TIME In HH: mm format, the hours and minutes are expressed in 24-hour notation. This API does not handle seconds as a request parameter.
DATETIME YYYY-MM-DD HH: Represents the date and hour in mm format.
BOOLEAN Represents either 'true' or 'false'.

HTTP Response

HTTP response specifications received by the Transactional Email API will be explained in this section.

Status Code

The Transactional Email API responds with the following status code:

Code Message Description
200 OK The request was successfully processed.
204 (No messages)
400 Bad Request The request was not processed successfully due to the reasons such as an invalid parameter was requested.
401 Unauthorized User authentication failed.
403 Forbidden Refused to execute a request from a user due to IP restrictions or access control.
404 Not Found Requested URL does not esxist.
500 Internal Server Error The request could not be executed due to a problem inside the system.


The Transactional Email API responds to JSON or XML format messages according to the format specified in the URL. The d'ownload' action performs a file download.

The format of these response messages is distinguish by the HTTP response header Content-Type.

Content-Type Description
application/json Responds to JSON formatted messages.
application/xml Responds to XML formatted messages.
application/octet-stream Downloads the file.'download' action responds in this format.If the status code is other than 200, an error message will be returned in the format specified in the request.


The Transactional Email API responds with the following message:


This message responds when a request to edit data, such as add /edit/delete, is successful.

    "message" : "User example1.hde was deleted"
<message>User was deleted<message>


This message responds when the request fails.

    "errors" : [
            "code" : "01-004",
            "field" : "api_user",
            "message" : "api_user is required."
            "code" : "01-004",
            "field" : "api_key",
            "message" : "api_key is required."
        <message>api_user is required.</message>
        <message>api_key is required.</message>

Target data does not exist

If the target data does not exist in a search operation such as the 'list' action, the following message is returned with status code 204.

    "message" : "The process was finished normally but the data was not found."
<message>The process was finished normally but the data was not found."</message>

Search results

If the target data exists in the search operation such as 'list action', the message is returned in the format specified for each URL. For more about the message, refer to the manual of each API.

Error Message

Common error messages for the Transactional Email API is explained in the following. Apart from the common error message an error message defined for each API may be returned.

Code Message (en) Message (ja)
01-001 A system error has occurred.Please contact your system administrator. システムエラーが発生しました。システム管理者に連絡してください。
01-002 HTTP requests using the GET method are not allowed. Please use the POST Method. GETメソッドを使用したHTTPリクエストは許可していません。POSTメソッドを使用してください。
01-003 User authentication was failed. ユーザ認証に失敗しました。
01-004 {0} is arequired item. {0}は必須項目です。
01-005 api_user does not have permission to perform the requested process. APIユーザはリクエストされた処理を実行する権限がありません。
01-101 {0} was not found. {0} が見つかりませんでした。


Transactional Email API security will be explained in this section.

User Authentication

The Transactional Email API perform a user authentication that uses the api_user and api_key parameters included in the HTTP request. For API user registration please refer to "API user" in user guide.

Access Control by Authorization

The Transactional Email API can be used in two roles: API group administrator and API user. Following access authorizations​ can be granted to each API user.

Role Description
API group administrator Operation of the data reference/download, add, update, and delete is possible.
API user Operation of the data reference/download is possible.
Authorization Description
Data reference permission Access authority to API that can refer to data including email address.
Download permission Access authority to API that allows you to download data file including email addresses.

Access control by IP address

Checks the source IP address of the HTTP request and controls access. For access control settings please refer to "connection IP" of the user guide

Data encryption

When you download a file with the 'download' action, you can create a file to download in password-protected encrypted ZIP format. For data encryption settings please refer to "Transactional Email API" of the user guide.