'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 Business / Enterprise / OEM / 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

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), “name” part of the from address (from parameter) and reply to address (replyto 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 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.

JSON

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

XML

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

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.

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

Response

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

JSON

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

XML

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

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.

Mail Delivery Error

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

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