このドキュメントはAPIバージョン1のAPI仕様です。
最新バージョンのAPI仕様はAPIリファレンスを参照ください。
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(宛先)アドレスを入力します。メールアドレス形式を含め３つの書式（後述参照）で値を入力することができます。 |
cc | No | UTF-8 | Ccアドレスを入力します。メールアドレス形式を含め３つの書式（後述参照）で値を入力することができます。 |
bcc | No | UTF-8 | Bccアドレスを入力します。メールアドレス形式を含め３つの書式（後述参照）で値を入力することができます。 |
from | Yes | UTF-8 | From(差出人）アドレスをタイプ２形式（後述参照）で入力します。 |
replyto | No | UTF-8 | Reply-To(返信先）アドレスをタイプ２形式（後述参照）で入力します。 |
headers | No | UTF-8 | 任意のメールヘッダをJSON形式（後述参照）で入力します。 |
charset | No | ASCII | メールコンテンツの文字コードを指定します。ISO-2022-JP、UTF-8のいずれかを指定してください。 |
subject | Yes | UTF-8 | メールの件名を入力します。 |
text | Yes | UTF-8 | テキスト本文を入力します。制約：512KByte まで入力可能とします。 |
html | No | UTF-8 | HTML本文を入力します。制約：512KByte まで入力可能とします。 |
attachments | No | INTEGER | 添付ファイルを付与する場合、添付するファイルの数を入力します。 |
attachmentN | No | BINARY | ファイルを添付します。Nはファイル番号を意味し、1からattachmentsとなります。例えば、添付ファイルを3つ付与する場合、attachment1, attachment2, attachment3 各々にファイルを入力します。 |
メールアドレス書式
to, cc, bcc, from, replyto の各パラメータで入力可能な書式を説明します。
タイプ１
メモ
to, cc, bcc には単純なメールアドレス形式を入力することができます。タイプ１を使用した場合、メールヘッダにはメールアドレスのみがセットされます。
user@example.comタイプ２
表示名とメールアドレスをJSONで入力します。to, cc, bcc, from, replyto で使用することができます。タイプ２を使用して表示名を省略したい場合、name プロパティに ""（空文字列） を指定してください。
{
"name" : "Personal Name",
"address" : "user@example.com"
}タイプ３
タイプ２のJSONを配列形式とし、複数のメールアドレスを入力します。to, cc, bcc で使用することができます。タイプ３に指定できる最大メールアドレス数は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 で対象データを検索したり、その値を取得することができます。
JSON
[
{
"name" : "X-Mail-Category",
"value" : "campaign"
},
{
"name" : "X-Api-Data",
"value" : "jobid=989da13ddkl3adsaq"
}
]レスポンス
メールの送信に成功した場合、Message-Id ヘッダに付与した ID を返します。
JSON
{
"id": "\u003C7bedd290-a213-11e5-8344-06ff9846521b@node1\u003E"
}XML
<?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 形式で送信してください。 | |
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-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. | ウイルス検査サーバでタイムアウトが発生しました。 |
リクエスト例
添付ファイルなし
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' -