Email Sending API
Provides an API that allows you to send bulk emails or single emails.
Provides a mechanism to send bulk mails by specifying a list of recipient addresses and the email body as parameters. You can also use the merge characters to create emails with different content for each destination address.
It also provides an API that allows you to easily send a single mail. You can send an email by using this API If external communication by SMTP is not possible due to restrictions of the ISP or cloud where the application is located.
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://[hostname]/api/[version]/[resource]/[action].[format]
[hostname]Represents the host name that provide this API.[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.
Note
The Email Sending API is provided by the mail server, similar to SMTP.
Specifies the access point host according to the service plan as follows.
sandbox
The free trial allows you to connect to the following endpoints:
| Item | Value |
|---|---|
| End Point URL | https://sandbox.smtps.jp/api/v2/emails/send.json |
transactional-email
Pro plan allows you to connect to the following endpoints:
| Item | Value |
|---|---|
| End Point URL | https://SUBDOMAIN.smtps.jp/api/v2/emails/send.json |
*) SUBDOMAIN Is the domain name you applied for when you start using the service.
Standard plan allows you to connect to the following endpoints:
| Item | Value |
|---|---|
| End Point URL | https://te.smtps.jp/api/v2/emails/send.json |
Authentication
The Email Sending API performs 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.
HTTP Request
HTTP request specifications received by the Transactional Email API will be explained in this section.
Method
The Transactional Email API only accepts POST methods.
Note
The maximum size of POST that the API accepts depends on the receive size in the relay server settings(mail). The body text is 3 bytes for Japanese In case of UTF-8 and 1 byte for ASCII.However,It is encoded in Base64 and becomes about 130%. Since the attachment file encoded in Base64,It will be about 130% of the original file size.
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.
Specifies multipart/form-data since you need to upload the file If you want to send an email with an attachment.
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. |
- 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 the 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.
When specifying application/x-www-form-urlencoded (multipart/form-data)
Create the parameter name and the value set and then POST.
to use application/json
Create a JSON with the parameter name as property and POST it.
{
"api_user" : "smtp_api_user@example.com",
"api_key" : "a29yZWhhcGFzc3dvcmRkZXN1",
"to" : [
{
"name" : "Personal Name1",
"address" : "user1@example.com"
},
{
"name" : "Personal Name2",
"address" : "user2@example.com"
}
],
"from" : {
"name" : "customer support",
"address" : "support@example.co.jp"
},
"subject" : "~~~~shop：notification for member registration completion",
"text" : "((#name#)) This time, ....."
}
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 from -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. |
| 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. |
| 503 | Service Unavailable | The request could not be executed due to excessive access or server overload. |
Header
The Transactional Email API responds to JSON or XML format messages according to the format specified in the URL.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. |
Message
The Transactional Email API responds with the following message:
Successful
For the respond message when the request is successful, please refer to "Response" of each API specification.
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>
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 | System error was occurred. Please contact system administrator. | システムエラーが発生しました。システム管理者に連絡してください。 |
| 01-002 | HTTP Request which use GET Method is not permitted. Please use POST Method. | GETメソッドを使用したHTTPリクエストは許可していません。POSTメソッドを使用してください。 |
| 01-003 | User authentication was failed. | ユーザ認証に失敗しました。 |
| 01-004 | {0} is required. | {0}は必須項目です。 |
| 01-005 | The api_user does not have a role which is to perform requested process. | APIユーザーはリクエストされた処理を実行する権限がありません。 |
| 01-006 | Connected IP does not allow to access API. Please confirm source IP setting. | 接続IPはAPIにアクセスすることはできません。接続元IP設定を確認してください。 |
| 01-007 | An error occurred when executing login. | ログインを実行するときにエラーが発生しました。 |
| 01-008 | Invalid JSON format. | JSON形式が不正です。 |
| 01-009 | Request data is invalid. Check the character code. | リクエストデータが不正です。文字コードを確認ください。 |
| 01-101 | {0} was not found. | {0}が見つかりませんでした。 |
| 01-102 | Server configuration is incorrect. Please contact system administrator. | サーバ設定が不正です。システム管理者にお問合せください。 |
| 02-001 | {0} is required. | {0}は必須項目です。 |
| 02-002 | Please enter a value more than {0} characters. | {0}文字以上の値を入力してください。 |
| 02-003 | Please enter a value less than {0} characters. | {0}文字以下の値を入力してください。 |
| 02-004 | Please enter a numeric value. | 数値を入力してください。 |
| 02-005 | Please enter a number in the range of {0} - {1}. | {0}-{1}の範囲の数値を入力してください。 |
| 02-006 | Please enter only the alphabet, number and symbol characters. | 英数字・記号のみを入力してください。 |
| 02-007 | Please enter the date format (YYYY-MM-DD). | 日付形式(YYYY-MM-DD)を入力してください。 |
| 02-008 | {0} is invalid date. | {0}は不正な日付です。 |
| 02-009 | Please enter the time format (HH:mm). | 時刻形式(HH:mm)を入力してください。 |
| 02-010 | {0} is invalid time. | {0}は不正な時刻です。 |
| 02-011 | Please enter the date-time format (YYYY-MM-DD HH:mm). | 日時形式(YYYY-MM-DD HH:mm)を入力してください。 |
| 02-012 | {0} is invalid date-time. | {0}は不正な日時です。 |
Security
Email sending API security will be explained in this section.
User Authentication
Email sending API performs 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.
Note
Since the Email Sending API authenticates the user by SMTP authentication, "SMTP" must be checked on.