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 では、表示名、メールアドレスの他に任意の差込み文字を入力することができます。

Emails/send

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

[
  {
    "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 で対象データを検索したり、 その値を取得することができます。

[
  {
    "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,228(512K) 文字 まで入力可能とします。
html No UTF-8 HTML本文を入力します。
制約:524,228(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 には、差込み文字を以下のようにパラメータで指定します。

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 に差し込んだ値は、BouncesDeliveries API で取得することができます。

件名

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

本文

山田太郎 様

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

商品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

レスポンス

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

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>
プロパティ 説明
message このリクエストの処理結果

エラーメッセージ

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


パラメータエラー

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

フィールド エラーコード メッセージ(en) メッセージ(ja)
to 11-004 You have exceeded the maximum numbers of address. 指定可能なメールアドレス数を超えました。
to,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. アクションが不正です。

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,228(512K) 文字 まで入力可能とします。
html No UTF-8 HTML本文を入力します。
制約:524,228(512K) 文字 まで入力可能とします。
attachments No INTEGER 添付ファイルを付与する場合、添付するファイルの数を入力します。
デフォルト:0
範囲:0-10
attachmentN No BINARY ファイルを添付します。Nはファイル番号を意味し、1からattachmentsとなります。例えば、添付ファイルを3つ付与する場合、attachment1, attachment2, attachment3 各々にファイルを入力します。

レスポンス

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

{
  "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. アクションが不正です。

メール送信エラー

メールサーバとの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証明書の有効期限が切れています。