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(宛先)アドレスを入力します。メールアドレス形式を含め３つの書式（後述参照）で値を入力することができます。 |
| 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のいずれかを指定してください。 デフォルト: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となります。例えば、添付ファイルを３つ付与する場合、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 で対象データを検索したり、その値を取得することができます。
[
{
"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 形式で送信してください。 | |
| 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. | ウイルス検査サーバでタイムアウトが発生しました。 |
リクエスト例
添付ファイルなし
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/v1/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/v1/emails/send.json