このドキュメントはAPIバージョン1のAPI仕様です。

最新バージョンのAPI仕様はAPIリファレンスを参照ください。

Emails

Emails は HTTP でメールを送信する機能を提供します。 このAPIはメールサーバーが提供します。


send

Emails/send は、HTTP でメールを送信する機能を提供します。

リクエスト

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

アクセス制御

api_user, api_key によるSMTP認証を行います。

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

api_user ごとの最大同時接続数は 10 となります。


パラメータ

パラメータ 必須 データ型 説明
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形式(後述参照)で入力します。
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 テキスト本文を入力します。
制約:512KByte まで入力可能とします。
html No UTF-8 HTML本文を入力します。
制約:512KByte まで入力可能とします。
attachments No INTEGER 添付ファイルを付与する場合、添付するファイルの数を入力します。
デフォルト:0
範囲:0-10
attachmentN No BINARY ファイルを添付します。Nはファイル番号を意味し、1からattachmentsとなります。例えば、添付ファイルを3つ付与する場合、attachment1, attachment2, attachment3 各々にファイルを入力します。

メールアドレス書式

to, cc, bcc, from, replyto の各パラメータで入力可能な書式を説明します。

タイプ1

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のJSONを配列形式とし、複数のメールアドレスを入力します。 to, cc, bcc で使用することができます。タイプ3に指定できる最大メールアドレス数は10です。

[
  {
    "name" : "Personal Name1",
    "address" : "user1@example.com"
  },
  {
    "name" : "Personal Name2",
    "address" : "user2@example.com"
  }
]

メールヘッダ

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

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

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

レスポンス

メールの送信に成功した場合、Message-Id ヘッダに付与した ID を返します。

{
  "id": "\u003C7bedd290-a213-11e5-8344-06ff9846521b@node1\u003E"
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<email>
  <id>7bedd290-a213-11e5-8344-06ff9846521b@node1</id>
</email>
プロパティ 説明
id Message-Id ヘッダに付与した ID

エラーメッセージ

メールの送信に失敗した場合、以下のエラーメッセージを返します。


パラメータエラー

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

フィールド エラーコード メッセージ(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 形式で送信してください。

メール送信エラー

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