Emails

'Emails' provides an API that allows you to send bulk emails or single emails. This API provided by management console.For access point host please refer to shared specification.

Parameter Format

'Emails' have parameters that specify the email address such as 'from', 'to', 'cc'. These parameters are specified in JSON format with properties such as display name, email address, etc.

Mail Address

This section describes the formats that can be input for the 'to', 'cc', 'bcc', 'from', and 'replyto' parameters. For the specifications of e-mail addresses that can be managed, please refer to "Common Specifications" in the User Guide.

Type 1

You can input a simple email address format in 'to', 'cc', 'bcc' of 'Emails/send'. When type 1 is used, only the email address is set in the email header.

user@example.com

Type 2

Input the display name and email address in JSON. It can be used with 'to', 'cc', 'bcc', 'from', 'replyto'. If you want to abbreviate the display name using type 2, specify "" (empty string) in the name property.

{
"name" : "Personal Name",
"address" : "user@example.com"
}

Type 3

Type 2 is an array format and you can enter multiple email addresses.

Emails/bulk

Create personalized emails for each recipient using merge characters and send them in bulk. The maximum number of email addresses that can be specified for to is 1000. In emails/bulk, you can input any merge characters in addition to the display name and email address. The maximum number of JSON properties for each destination is 100. The JSON property value can be a specify character string of up to 5 Kbytes.

Emails/send

Send by specifying multiple email addresses in the 'to', 'cc', 'bcc' header of a single email. The maximum number of email addresses that can be specified for each header is 10.You cannot use merge characters in Emails / send.

[
{
    "name" : "Personal Name1",
    "address" : "user1@example.com",
    "item1" : "merge characters＃1",
    "item2" : "merge characters＃2"
},
{
    "name" : "Personal Name2",
    "address" : "user2@example.com",
    "item1" : "merge characters＃1",
    "item2" : "merge characters＃2"
}
]

Mail header

If you want to add your own email header to the emails you send with the API Specify JSON in the following format in the headers parameter. You can create filter patterns for mail forwarding, delivery priority, and delivery prohibition time zone by using mail header you added.

You can ssearch the target data with Bounces, Deliveries of Transactional Email API and get that value by using the mail header X-Api-Data to add application management information.

JSON

[
{
    "name" : "X-Mail-Category",
    "value" : "campaign"
},
{
    "name" : "X-Api-Data",
    "value" : "jobid=989da13ddkl3adsaq"
}
]

bulk

This API can be used in Pro plan.

Emails/bulk provides a mechanism for using merge characters to create personalized emails for each recipient and send them in bulk.

Request

/api/v2/emails/bulk.[json|xml]

Access Control

SMTP authentication is performed by api_user and api_key.

The maximum number of simultaneous connections is 10.

Warning

Please use SMTP as an API user (SMTP check-on).

Parameter

Parameter	Required	Data Type	Description
api_user	Yes	ASCII	Specifies the ID used for SMTP authentication.
api_key	Yes	ASCII	Specifies the secret key used for SMTP authentication.
to	Yes	UTF-8	Input the To (destination) address.Input the value in Type3 format, including your email address and merge characters.
from	Yes	UTF-8	Input the From (sender) address in Type2 format.
envfrom	No	ASCII	Input the mail address that bounce mail will return to in Type1 format. If there are no restrictions, mail address that specified in parameter 'from' will be used for 'envfrom'.If you perform the rewrite settings of envelope From on "server settings"＞"advance settings",rewrite settings will have the priority.
replyto	No	UTF-8	Input the Reply-To(reply address）address in Type2 format.
headers	No	UTF-8	Input any email header in JSON format.
charset	No	ASCII	Specifies the character code of the mail content.Please specify either ISO-2022-JP or UTF-8. default:UTF-8
subject	Yes	UTF-8	Input the subject of the mail. restrictions：You can input up to 512 characters.
text	Yes	UTF-8	Input the text body. restrictions：You can input up to 524,288(512K) characters.
html	No	UTF-8	Input the HTML body. restrictions：You can input up to 524,288(512K) characters.
attachments	No	INTEGER	Input the number of attachment files If you want to attach a file. default:0 span:0-10
attachmentN	No	BINARY	Attach the file.N represents the file number,attachment from 1.For example,if you want to add 3 attachments, input the files for each attachment1, attachment2, and attachment3.

Merge Characters

Mwerge character is a function to create a personalized mail with different contents for each recipient,by embedding the property specified in the type3 format JSON object as a variable in the subject or body.

Merge characters can be used in subject (subject parameter), email body (text parameter, html parameter), mail header (value of headers parameter).

The place where the merge character is expanded, a variable called "merge tag" is decribed in the format of ((# property name #)) .

For 'to', specify the merge character as a parameter as shown below.

*Each parameter of the merge character is up to 5kbyte (in UTF-8).

to parameter（destination address list）

[
{
    "name" : "Yamada Taro",
    "address" : "user1@example.com",
    "item1" : "Product1：http://example.com/sale/item1.html",
    "item2" : "Product2：http://example.com/sale/item2.html",
    "customer-id" : "CID0001"
},
{
    "name" : "Suzuki Hanako",
    "address" : "user2@example.com",
    "item1" : "Product3：http://example.com/sale/item3.html",
    "item2" : "Product4：http://example.com/sale/item4.html",
    "customer-id" : "CID0002"
}
]

When writing HTML email parts in JSON, you need to be aware of escape. Escape is required for below characthers.

Escape notation	Previous characters	Description
\"	"	Double quotation
\\	\	backslasj
\/	/	slash
\n		new line
\t		tab

Escape example

{
"tag" : "<a href=\"http:\/\/example.com\/sale\/item1.html\">product1</a>"
}

Subject (subject parameter), email body (text parameter, html parameter), And, describe "insertion tag" in the mail header (value of headers parameter).

Describe the "merge tag" in subject (subject parameter),email body (text parameter, html parameter), mail header (value of headers parameter)

subject parameter（subject）

○○shop：Notification for valuable information to ((#name#)) 

text parameter（mail body)

((#name#)) 

A member-only sale is happening now.
Click here for recommended products

((#item1#))

((#item2#))

headers parameter（mail header）

JSON

[
{
    "name" : "X-Api-Data",
    "value" : "((#customer-id#))"
}
]

The email created for each recipient using the merge character is as follows.

The value merged in the mail header X-Api-Data can be obtained by Bounces or Deliveries API.

If the sending header value is long

Due to the specification of Email, long header values cannot be written as they are. Therefore, line breaks should be inserted in the header value as appropriate.

In the case of a header that extends over multiple lines, WSP characters are inserted at the beginning of the second and subsequent lines due to the header specifications. In this case, since JSON strings, etc. are not interpreted, spaces may be inserted in unintended places.

When using long header values in the headers parameter (X-Api-Data, etc.), it is recommended that JWT conversion, Base64 encoding, etc. be performed before sending the e-mail so that unintended WSP characters can be removed.

subject

~~~~shop：Notification for valuable information to Mr. Yamada Taro

body

Mr. Yamada Taro

A member-only sale is happening now.
Click here for recommended products

Product1：http://example.com/sale/item1.html

Product2：http://example.com/sale/item2.html

Mail header

Delivered-To: user1@example.com
Received: by xxx.xxx.xxx.xxx with SMTP id y192csp129996vsc;
        Fri, 28 Jul 2017 02:25:10 -0700 (PDT)
:
X-Api-Data: CID0001

Response

If the request is successful,following message will be returned.

JSONXML

{
“message” : “Your email sending request was accepted.”
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bulk>
<message>Your email sending request was accepted.</message>
</bulk>

Property	Description
message	Processing result of this request

Error Message

If the request fails, following error message will be returned.

Parameter Error

If an error occurs in the parameter check, the following error message will be returned.

Field	Error code	Message (en)	Message (ja)
to	11-004	The number of e-mail addresses that can be specified has been exceeded.	指定可能なメールアドレス数を超えました。
	11-021	Some properties in 'to' parameter has exceed the maximum size.(5120 bytes).	toパラメーターのプロパティに最大サイズ(5120byte)を超えているものが存在します。
	11-022	Number of properties in 'to' parameter has exceed the maximum size.(100).	toパラメーターのプロパティ数が最大サイズ(100個)を超えているものが存在します。
from,replyto,envfrom	11-005	{0} is an invalid mail address.	{0}は不正なメールアドレスです。
to,from, replyto,headers	11-006	The value specification method is invalid. (Invalid JSON format).	値の指定方法が不正です。(JSONフォーマット不正)
api_key	11-007	The number of connectable connections has been exceeded.	接続可能なコネクション数を超えました。
text,html	11-008	Delivery failed because the mail size is too large.	メールサイズが大きすぎるため送信できませんでした。
headers	11-009	{0} is required.	{0}は必須項目です。
attachments	11-010	The value {0} does not match the actual number of attachments.T	値{0}と実際の添付ファイル数がマッチしません。
charset	11-011	The value specification method is invalid.(Invalid charset).	値の指定方法が不正です。（不正なcharset）
attachmentN	11-012	Attachment file format is invalid.	添付ファイルの形式が不正です。
headers	11-013	The value specification method is invalid.(Invalid header name).	値の指定方法が不正です。（不正なheader name）
headers	11-014	The header length has exceeded the limit.(998 bytes).	ヘッダの長さが制限を超えました。（998バイト）
	11-015	The Content-Type is invalid. Please send using multipart/form-data format.	コンテントタイプが不正です。multipart/form-data 形式で送信してください。
subject	11-016	Subject length has exceeded the limit.(512 letters)	subject の長さが制限を超えました。（512文字）
attachments	11-017	The value specification method is invalid.(Invalid attachments).	値の指定方法が不正です（不正な attachments）
	11-018	The value specification method is invalid.(Invalid parameter name).	値の指定方法が不正です。（不正なパラメータ名）
	11-019	The action is invalid.	アクションが不正です。

Request Example

Without attachment file

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'to=[{"name":"test","address":"test@example.com"}]' -d 'from={"name":"test","address":"test@test.smtps.jp"}' -d 'subject=test send to ((#name#))' -d 'text=test send to ((#name#))' https://sandbox.smtps.jp/api/v2/emails/bulk.json

With attachment file

curl -X POST -F 'api_user=testuser' -F 'api_key=password' -F 'to=[{"name":"test","address":"test@example.com"}]' -F 'from={"name":"test","address":"test@test.smtps.jp"}' -F 'subject=test send to ((#name#))' -F 'text=test send to ((#name#))' -F 'attachments=1' -F 'attachment1=@ファイルパス' https://sandbox.smtps.jp/api/v2/emails/bulk.json

send

Emails/send provides a function to send a single email.

Request

/api/v2/emails/send.[json|xml]

Access Control

SMTP authentication is performed by api_user and api_key. The maximum number of simultaneous connections is 10.

Warning

Please use SMTP as an API user (SMTP check-on).

Parameters

Parameter	Required	Data Type	Description
api_user	Yes	ASCII	Specifies the ID used for SMTP authentication.
api_key	Yes	ASCII	Specifies the secret key used for SMTP authentication.
to	Yes	UTF-8	Input the To (destination) address.You can input the value of the email address in three formats.
cc	No	UTF-8	Input the cc address.You can input the value of the email address in three formats.
bcc	No	UTF-8	Input the bcc address.You can input the value of the email address in three formats.
from	Yes	UTF-8	Input the From (sender) address in Type2 format.
envfrom	No	ASCII	Input the mail address that bounce mail will return to in Type1 format If there are no restrictions, mail address that specified in parameter 'from' will be used for 'envfrom'.If you perform the rewrite settings of envelope from on "server settings"＞"advance settings",rewrite settings will have the priority.
replyto	No	UTF-8	Input the Reply-To(reply address）address in Type2 format.
headers	No	UTF-8	Input any email header in JSON format.
charset	No	ASCII	Specifies the character code of the mail content.Please specify either ISO-2022-JP or UTF-8. default:UTF-8
subject	Yes	UTF-8	Input the subject of the mail. restrictions：You can input up to 512 characters.
text	Yes	UTF-8	Input the text body. restrictions：You can input up to 524,288(512K) characters.
html	No	UTF-8	Input the HTML body. restrictions：You can input up to 524,288(512K) characters.
attachments	No	INTEGER	Input the number of attachment files If you want to attach a file. default:0 span:0-10
attachmentN	No	BINARY	Attach the file.N represents the file number,attachment from 1.For example,if you want to add 3 attachments, input the files for each attachment1, attachment2, and attachment3.

Response

If the request is successful, the ID given to the Message-Id header of the created email will be returned.

JSONXML

{
"id": "\u003C7bedd290-a213-11e5-8344-06ff9846521b@node1\u003E"
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<email>
<id>&lt;7bedd290-a213-11e5-8344-06ff9846521b@node1&gt;</id>
</email>

Property	Description
id	ID given to the Message-Id header

Error Message

If the request fails, following error message will be returned.

Parameter Error

If an error occurs in the parameter check, the following error message will be returned.

Field	Error Code	Message (en)	Message (ja)
to,cc,bcc	11-004	The number of e-mail addresses that can be specified has been exceeded.	指定可能なメールアドレス数を超えました。
to,cc,bcc, from,replyto	11-005	{0} is an invalid mail address.	{0}は不正なメールアドレスです。
to,cc,bcc, from,replyto, headers	11-006	The value specification method is invalid. (Invalid JSON format).	値の指定方法が不正です。(JSONフォーマット不正)
api_key	11-007	The number of connectable connections has been exceeded.	接続可能なコネクション数を超えました。
text,html	11-008	Delivery failed because the mail size is too large.	メールサイズが大きすぎるため送信できませんでした。
headers	11-009	{0} is required.	{0}は必須項目です。
attachments	11-010	The value {0} does not match the actual number of attachments.	値{0}と実際の添付ファイル数がマッチしません。
charset	11-011	The value specification method is invalid.(Invalid charset).	値の指定方法が不正です。（不正なcharset）
attachmentN	11-012	Attachment file format is invalid.	添付ファイルの形式が不正です。
headers	11-013	The value specification method is invalid.(Invalid header name).	値の指定方法が不正です。（不正なheader name）
headers	11-014	The header length has exceeded the limit. (998 bytes).	ヘッダの長さが制限を超えました。（998バイト）
	11-015	The Content-Type is invalid. Please send using multipart/form-data format.	コンテントタイプが不正です。multipart/form-data 形式で送信してください。
attachments	11-017	Specified value has invalid. (Invalid attachment value).	値の指定方法が不正です（不正な attachments)
	11-018	The value specification method is invalid.(Invalid parameter name).	値の指定方法が不正です。（不正なパラメータ名）
	11-019	The action is invalid.	アクションが不正です。
headers	11-020	Cannot specify name of to, cc, bcc, from, reply-to, subject in headers.	headersには、to, cc, bcc, from, reply-to, subject は指定できません。

Mail Delivery Error

If an error occurs during SMTP communication with the mail server, the following error message will be returned.

Error Code	Message (en)	Message (ja)
13-001	An unexpected error has occurred.	予期しないエラーが発生しました。
13-002	Can not connect to MTA	MTAに接続できませんでした。
13-003	Improper email address has received.	不正なメールアドレスを受信しました。
13-004	User authentication has failed.	ユーザ認証に失敗しました。
13-005	The number of connections limited by the group has been exceeded.	グループで制限されているコネクション数を超えました。
13-006	Can not send email with specified 'from' address. Please set up DKIM.	指定されたFromアドレスでメール送信することはできません。DKIMを設定してください。
13-007	Message size has exceeded the value limit	メッセージサイズが制限値を超えました。
13-008	The disk usage threshold has been exceeded.	ディスク使用量の閾値を超えました。
13-009	S/MIME certificate is expired.	S/MIME証明書の有効期限が切れています。
13-010	The mail is infected by a virus.	ウィルスを検出しました。
13-011	The virus inspection server has timed out.	ウイルス検査サーバでタイムアウトが発生しました。

Note

About 13-010, 13-011, the optional subscription "Virus Detection" is needed.

Request Example

Without attachment file

curl -X POST -d 'api_user=testuser' -d 'api_key=password' -d 'to=test@example.com' -d 'from={"name":"test","address":"test@test.smtps.jp"}' -d 'subject=test' -d 'text=test' https://sandbox.smtps.jp/api/v2/emails/send.json

With attachment file

curl -X POST -F 'api_user=testuser' -F 'api_key=password' -F 'to=test@example.com' -F 'from={"name":"test","address":"test@test.smtps.jp"}' -F 'subject=test' -F 'text=test' -F 'attachments=1' -F 'attachment1=@file peass' https://sandbox.smtps.jp/api/v2/emails/send.json