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

Version

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.

Access Point Host and URL

https://api.smtps.jp/transaction/[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.

Authentication

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.

Method

The Transactional Email API only accepts POST methods.

Header

Transactional Email API references the following header fields:

Content Type

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

Parameter

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

JSON

{
"api_user" : "http_api_user@example.com",
"api_key" : "a29yZWhhcGFzc3dvcmRkZXN1",
"server_composition" : "sandbox",
"to" : "@example.com",
"status" : "failed",
"search_option" : {
    "to" : "part",
    "from" : "full",
    "api_data" : "full"
}
}

Data Type

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

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:

Header

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.

Message

The Transactional Email API responds with the following message:

Successful

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

JSON

{
    "message" : "User example1.hde was deleted"
}

XML

<message>User example1@hennge.com was deleted<message>

Error

This message responds when the request fails.

JSON

{
    "errors" : [
        {
            "code" : "01-004",
            "field" : "api_user",
            "message" : "api_user is required."
        },
        {
            "code" : "01-004",
            "field" : "api_key",
            "message" : "api_key is required."
        }
    ]
}

XML

<errors>
    <error>
        <code>01-004</code>
        <field>api_user</field>
        <message>api_user is required.</message>
    </error>
    <error>
        <code>01-004</code>
        <field>api_key</field>
        <message>api_key is required.</message>
    </error>
</errors>

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.

JSON

{
    "message" : "The process was finished normally but the data was not found."
}

XML

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

Security

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.

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.