Transactional Email API
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.
| Item | Value |
|---|---|
| Protocol | HTTPS |
| Character code | UTF-8 |
| Newline code | LF |
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:
| 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.
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 | 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 default:0 |
| r | No | INTEGER | Number of records of data that will be acquired. default:10 |
- 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" : "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.
| 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. |
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.
| 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. |
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.
{
"message" : "User example1.hde was deleted"
}
<message>User example1@hennge.com was deleted<message>
Error
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."
}
]
}
<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.
{
"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} が見つかりませんでした。 |
| 10-001 | System error was occurred. Please contact system administrator. | システムエラーが発生しました。システム管理者に連絡してください。 |
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.
| 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.