Emails

Emails は一括メール、または、単一メールを送信することができるAPIを提供します。このAPIはメールサーバーが提供します。接続先ホストについては共通仕様を参照ください。

パラメータの書式

Emails は、from, to, cc などメールアドレスを指定するパラメータを持ちます。これらのパラメータは表示名、メールアドレスなどのプロパティを持つ JSONフォーマットで指定します。

メールアドレス

to, cc, bcc, from, replyto の各パラメータで入力可能な書式を説明します。取り扱えるメールアドレスの仕様については、ユーザーガイドの「共通仕様」を参照ください。

タイプ1

Emails/send の to, cc, bcc には単純なメールアドレス形式を入力することができます。タイプ1を使用した場合、メールヘッダにはメールアドレスのみがセットされます。

user@example.com

タイプ2

表示名とメールアドレスをJSONで入力します。to, cc, bcc, from, replyto で使用することができます。タイプ2を使用して表示名を省略したい場合、name プロパティに ""（空文字列）を指定してください。

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

タイプ3

タイプ2を配列形式とし、複数のメールアドレスを入力することができます。

Emails/bulk

差込み文字を使用して、宛先ごとにパーソナライズドされたメールを生成し、一括送信します。to に指定できる最大メールアドレス数は1000です。

Emails/bulk では、表示名、メールアドレスの他に任意の差込み文字を入力することができます。各宛先毎のJSONプロパティの最大数は100個までです。JSONプロパティの値には、最大5Kbytesまでの文字列を指定することができます。

Emails/send

単一メールの to, cc, bcc ヘッダに複数のメールアドレスを指定して送信します。指定できる最大メールアドレス数は各ヘッダごとに10です。Emails/send では、差込み文字は使用できません。

JSON

[
{
    "name" : "Personal Name1",
    "address" : "user1@example.com",
    "item1" : "差込文字＃1",
    "item2" : "差込文字＃2"
},
{
    "name" : "Personal Name2",
    "address" : "user2@example.com",
    "item1" : "差込文字＃1",
    "item2" : "差込文字＃2"
}
]

メールヘッダ

APIで送信するメールに独自のメールヘッダを追加したい場合、headers パラメータに以下形式のJSONを指定します。追加したメールヘッダを使って、メール転送、配信優先度、配信禁止時間帯のフィルターパターンを作成することができます。

また、メールヘッダ X-Api-Data を使用してアプリケーションの管理情報を追加すると、Transactional Email API の Bounces, Deliveries で対象データを検索したり、その値を取得することができます。

JSON

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

bulk

このAPIはProプランで利用できます

Emails/bulk は、差込み文字を使用して、宛先ごとにパーソナライズドされたメールを生成し、一括送信する仕組みを提供します。

リクエスト

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

アクセス制御

api_user, api_key によるSMTP認証を行います。最大同時接続数は10です。

注意

APIユーザにてSMTPを使用する（SMTPチェックオン）としてください。

パラメータ

パラメータ	必須	データ型	説明
api_user	Yes	ASCII	SMTP認証に使用するIDを指定します。
api_key	Yes	ASCII	SMTP認証に使用するシークレットキーを指定します。
to	Yes	UTF-8	To(宛先)アドレスを入力します。メールアドレスや差込み文字を含む、タイプ3形式で値を入力します。
from	Yes	UTF-8	From(差出人）アドレスをタイプ2形式で入力します。
envfrom	No	ASCII	バウンスメールの返却先となるメールアドレスをタイプ1形式で入力します。指定が無い場合、パラメータ from で指定したメールアドレスを envfrom に使用します。「サーバー設定」＞「高度な設定」でエンベロープFromの書き換え設定を行った場合、書き換え設定が優先されます。
replyto	No	UTF-8	Reply-To(返信先）アドレスをタイプ2形式で入力します。
headers	No	UTF-8	任意のメールヘッダをJSON形式で入力します。
charset	No	ASCII	メールコンテンツの文字コードを指定します。ISO-2022-JP、UTF-8のいずれかを指定してください。デフォルト:UTF-8
subject	Yes	UTF-8	メールの件名を入力します。制約：512 文字まで入力可能とします。
text	Yes	UTF-8	テキスト本文を入力します。制約：524,288(512K) 文字まで入力可能とします。
html	No	UTF-8	HTML本文を入力します。制約：524,288(512K) 文字まで入力可能とします。
attachments	No	INTEGER	添付ファイルを付与する場合、添付するファイルの数を入力します。デフォルト:0 範囲:0-10
attachmentN	No	BINARY	ファイルを添付します。Nはファイル番号を意味し、1からattachmentsとなります。例えば、添付ファイルを3つ付与する場合、attachment1, attachment2, attachment3 各々にファイルを入力します。

差込み文字

差込み文字は、タイプ3形式のJSONオブジェクトに指定したプロパティを件名や本文に変数にして埋め込むことで、宛先ごとに内容が異なるパーソナライズドメールを作成するための機能です。

差込み文字は、件名（subject パラメータ）, メール本文（text パラメータ、html パラメータ）,および、メールヘッダ（headers パラメータの value）に使用することができます。差込み文字を展開する箇所には、「差込みタグ」と呼ぶ変数を、((#プロパティ名#)) の書式で記述します。

to には、差込み文字を以下のようにパラメータで指定します。 ※差し込み文字の各パラメータは（UTF-8で）最大5kbyteです。

メモ

差し込み文字が5kbyteを超える場合は、当社サポートにお問い合わせください。

to パラメータ（宛先アドレスリスト）

[
{
    "name" : "山田太郎",
    "address" : "user1@example.com",
    "item1" : "商品1：http://example.com/sale/item1.html",
    "item2" : "商品2：http://example.com/sale/item2.html",
    "customer-id" : "CID0001"
},
{
    "name" : "鈴木花子",
    "address" : "user2@example.com",
    "item1" : "商品3：http://example.com/sale/item3.html",
    "item2" : "商品4：http://example.com/sale/item4.html",
    "customer-id" : "CID0002"
}
]

JSONに、HTMLメールのパートを記述する場合は、エスケープに留意する必要があります。以下の文字はエスケープが必要です。

エスケープ表記	元の文字	説明
\"	"	ダブルクォーテーション
\\	\	バックスラッシュ
\/	/	スラッシュ
\n		改行
\t		タブ

エスケープ例

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

件名（subject パラメータ）, メール本文（text パラメータ、html パラメータ）,および、メールヘッダ（headers パラメータの value）には「差込みタグ」を記述します。

subject パラメータ（件名）

○○ショップ：((#name#)) 様にお得な情報をお届けします

text パラメータ（メール本文）

((#name#)) 様

会員様限定のセール開催中です。
お勧め商品はこちら。

((#item1#))

((#item2#))

headers パラメータ（メールヘッダ）

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

差込み文字を使用して宛先ごとに生成されるメールは以下のようになります。メールヘッダ X-Api-Data に差し込んだ値は、Bounces や Deliveries API で取得することができます。

ヘッダ値が長い場合の注意点

Email の仕様上、長いヘッダ値をそのまま記載することはできないため、ヘッダ値に対して適宜改行を入れることなります。

複数行にわたるヘッダの場合には、ヘッダの仕様上、2行目以降は行頭にスペースが入ります。このとき、JSON の文字列等の解釈はしないため、意図しない箇所にスペースが入ることがあります。

headersパラメータ（X-Api-Data等）で長いヘッダ値を使用する場合には、意図しないスペースを取り除けるように、JWT化やBase64エンコード等を実施した上でメール配信することを推奨します。

件名

○○ショップ：山田太郎 様にお得な情報をお届けします

本文

山田太郎 様

会員様限定のセール開催中です。
お勧め商品はこちら。

商品1：http://example.com/sale/item1.html

商品2：http://example.com/sale/item2.html

メールヘッダ

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

レスポンス

リクエストが成功した場合、以下のメッセージを返します。

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>

プロパティ	説明
message	このリクエストの処理結果

エラーメッセージ

リクエストが失敗した場合、以下のエラーメッセージを返します。

パラメータエラー

パラメータチェックでエラーが発生した場合、以下のエラーメッセージを返します。

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

リクエスト例

添付ファイルなし

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

添付ファイルあり

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 は、単一メールを送信する機能を提供します。

リクエスト

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

アクセス制御

api_user, api_key によるSMTP認証を行います。最大同時接続数は10となります。

注意

APIユーザにてSMTPを使用する（SMTPチェックオン）としてください。

パラメータ

パラメータ	必須	データ型	説明
api_user	Yes	ASCII	SMTP認証に使用するIDを指定します。
api_key	Yes	ASCII	SMTP認証に使用するシークレットキーを指定します。
to	Yes	UTF-8	To(宛先)アドレスを入力します。メールアドレスを3つの形式で値を入力することができます。
cc	No	UTF-8	Ccアドレスを入力します。メールアドレスを3つの形式で値を入力することができます。
bcc	No	UTF-8	Bccアドレスを入力します。メールアドレスを3つの形式で値を入力することができます。
from	Yes	UTF-8	From(差出人）アドレスをタイプ2形式で入力します。
envfrom	No	ASCII	バウンスメールの返却先となるメールアドレスをタイプ1形式で入力します。指定が無い場合、パラメータ from で指定したメールアドレスを envfrom に使用します。「サーバー設定」＞「高度な設定」でエンベロープFromの書き換え設定を行った場合、書き換え設定が優先されます。
replyto	No	UTF-8	Reply-To(返信先）アドレスをタイプ2形式で入力します。
headers	No	UTF-8	任意のメールヘッダをJSON形式で入力します。
charset	No	ASCII	メールコンテンツの文字コードを指定します。ISO-2022-JP、UTF-8のいずれかを指定してください。デフォルト:UTF-8
subject	Yes	UTF-8	メールの件名を入力します。制約：512文字まで入力可能とします。
text	Yes	UTF-8	テキスト本文を入力します。制約：524,288(512K) 文字まで入力可能とします。
html	No	UTF-8	HTML本文を入力します。制約：524,288(512K) 文字まで入力可能とします。
attachments	No	INTEGER	添付ファイルを付与する場合、添付するファイルの数を入力します。デフォルト:0 範囲:0-10
attachmentN	No	BINARY	ファイルを添付します。Nはファイル番号を意味し、1からattachmentsとなります。例えば、添付ファイルを3つ付与する場合、attachment1, attachment2, attachment3 各々にファイルを入力します。

ヘッダ値が長い場合の注意点

Email の仕様上、長いヘッダ値をそのまま記載することはできないため、ヘッダ値に適宜改行を入れることなります。

複数行にわたるヘッダの場合には、ヘッダの仕様上、2行目以降は行頭にスペースが入ります。このとき、JSON の文字列等の解釈はしないため、意図しない箇所にスペースが入ることがあります。

headersパラメータ（X-Api-Data等）などへ長いヘッダ値を使用する場合には、意図しないスペースを取り除けるように、JWT化や Base64エンコード等を実施した上でメール配信することを推奨します。

レスポンス

リクエストが成功した場合、生成したメールのMessage-Id ヘッダに付与した ID を返します。

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>

プロパティ	説明
id	Message-Id ヘッダに付与した ID

エラーメッセージ

リクエストが失敗した場合、以下のエラーメッセージを返します。

パラメータエラー

パラメータチェックでエラーが発生した場合、以下のエラーメッセージを返します。

フィールド	エラーコード	メッセージ（en)	メッセージ（ja)
to,cc,bcc	11-004	You have exceeded the maximum numbers of address.	指定可能なメールアドレス数を超えました。
to,cc,bcc, from,replyto	11-005	{0} is invalid mail address.	{0}は不正なメールアドレスです。
to,cc,bcc, from,replyto, headers	11-006	Specified value has invalid (Invalid JSON format).	値の指定方法が不正です。(JSONフォーマット不正)
api_key	11-007	You have exceeded the maximum numbers of connection.	接続可能なコネクション数を超えました。
text,html	11-008	Mail size was unable to send because it is too large.	メールサイズが大きすぎるため送信できませんでした。
headers	11-009	{0} is required.	{0}は必須項目です。
attachments	11-010	The value of {0} and the number of actual attachments doesn't match.	値{0}と実際の添付ファイル数がマッチしません。
charset	11-011	Specified value has invalid (Invalid charset format).	値の指定方法が不正です。（不正なcharset）
attachmentN	11-012	Specified attachment has invalid.	添付ファイルの形式が不正です。
headers	11-013	Specified value has invalid (Invalid header name format).	値の指定方法が不正です。（不正なheader name）
headers	11-014	Header length exceeds limit (998 bytes).	ヘッダの長さが制限を超えました。（998バイト）
	11-015	The Content-Type is invalid. Please request using multipart/form-data format.	コンテントタイプが不正です。multipart/form-data 形式で送信してください。
attachments	11-017	Specified value has invalid. (Invalid attachment value).	値の指定方法が不正です（不正な attachments）
	11-018	Specified value has 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 は指定できません。

メール送信エラー

メールサーバーとのSMTP通信でエラーが発生した場合、以下のエラーメッセージを返します。

エラーコード	メッセージ (en)	メッセージ (ja)
13-001	Unexcepted Exception has occurred.	予期しないエラーが発生しました。
13-002	Can not connect to MTA	MTAに接続できませんでした。
13-003	Bad address syntax.	不正なメールアドレスを受信しました。
13-004	User authentication failed.	ユーザ認証に失敗しました。
13-005	It has exceeded the number of connections that are limited by group.	グループで制限されているコネクション数を超えました。
13-006	Can not send email with specified from address. Please set up DKIM.	指定されたFromアドレスでメール送信することはできません。DKIMを設定してください。
13-007	Message size has exceeded the limit	メッセージサイズが制限値を超えました。
13-008	It has exceeded the threshold of disk usage.	ディスク使用量の閾値を超えました。
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.	ウイルス検査サーバーでタイムアウトが発生しました。

メモ

13-010, 13-011 の「ウイルス検知」については、ウイルスチェックオプションのご契約が必要となります。

リクエスト例

添付ファイルなし

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

添付ファイルあり

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=@ファイルパス' https://sandbox.smtps.jp/api/v2/emails/send.json