Email Sending API

一括メール、または、単一メールを送信することができるAPIを提供します。

宛先アドレスのリストとメール本文をパラメータに指定して一括メールを送信する仕組みを提供します。差込み文字を使用して、宛先アドレスごとに内容の異なるメールを生成することもできます。

また、1通のメールを簡単に送信することができるAPIを提供します。アプリケーションを配置しているISPやクラウドの制限によりSMTPによる外部通信ができない場合、このAPIを利用することでメールを送信することができます。

バージョン

POSTパラメータや応答メッセージのフォーマットはAPIのバージョンによって異なります。利用するバージョンのAPI仕様を参照ください。

現在のバージョンは、2です。

バージョン1のAPI仕様はこちらを参照ください。

共通仕様

このセクションでは、Email Sending API の共通仕様について説明します。

項目	値
プロトコル	HTTPS
文字コード	UTF-8
改行コード	LF

接続先ホストとURL

https://[hostname]/api/[version]/[resource]/[action].[format]

[hostname]は、このAPIを提供するホスト名を表します。
[version]は、APIバージョンを表します。v2 と v1 が指定できます。
[resource]は、操作対象のリソースを表します。
[action]は、操作を表します。
[format]は、レスポンスメッセージのフォーマットを表します。json と xml が指定できます。

メモ

Email Sending API は、SMTPと同様にメールサーバーが機能を提供します。

サービスプランにより接続先ホストを以下の通り指定してください。

sandbox

無料トライアルでは、以下のエンドポイントに接続することができます。

項目	値
エンドポイントURL	https://sandbox.smtps.jp/api/v2/emails/send.json

transactional-email

ProStandard

Pro プランでは、以下のエンドポイントに接続することができます。

項目	値
エンドポイントURL	https://SUBDOMAIN.smtps.jp/api/v2/emails/send.json

メモ

SUBDOMAINは、サービス利用開始時に申請頂いたドメイン名です。

Standard プランでは、以下のエンドポイントに接続することができます。

項目	値
エンドポイントURL	https://te.smtps.jp/api/v2/emails/send.json

認証

Email Sending API は、HTTPリクエストに含まれる api_user, api_key パラメータを使用したユーザ認証を行います。

APIユーザの登録方法については、ユーザガイドの「APIユーザ」を参照ください。

HTTPリクエスト

このセクションでは、Email Sending API が受信するHTTPリクエストの仕様について説明します。

メソッド

Email Sending API は、POSTメソッドのみを受け付けます。

メモ

API が受け付ける POST の最大サイズは、リレーサーバ設定の（メールの）受信サイズにより決まります。

本文テキストは、UTF-8 の場合は日本語が3バイト、ASCII が1バイトですが、それが Base64 でエンコードされて約 130% になります。添付ファイルは Base64 でエンコードされるので、元のファイルサイズの約 130% になります。

ヘッダ

Email Sending API は、以下のヘッダフィールドを参照します。

ヘッダフィールド	説明
Accept-Language	Email Sending APIが応答するメッセージの言語タイプを指定します。 en または ja のいずれかを指定します。言語指定が無いまたは左記以外の言語を指定された場合、en で動作します。

コンテンツタイプ

通常は、application/x-www-form-urlencoded または application/json を指定します。

添付ファイル付きメールを送信する場合は、ファイルアップロードが必要となるため、multipart/form-data を指定します。

注意

application/json は、バージョン2からサポートしました。バージョン1では使用できません。

パラメータ

Email Sending API は全てのHTTPリクエストに、ユーザ認証を行うための api_user, api_key を含める必要があり、かつ、URLごとに定義されたパラメータを送信する必要があります。

このドキュメントは以下フォーマットに従い、パラメータの説明を記述します。

パラメータ	必須	データ型	説明
api_user	Yes	ASCII	ユーザ認証に使用するID
api_key	Yes	ASCII	ユーザ認証に使用するシークレットキー

パラメータ：POSTするパラメータの名前。
必須：このパラメータが必須である場合、Yes。
データ型：パラメータ値のデータ型。（後述、データ型を参照）
説明：このパラメータに関する説明。

デフォルト値、入力値の範囲などの制限があるパラメータについては、説明欄に以下の書式で記載します。

デフォルト：(デフォルト値)
範囲：min=(最小値) / max=(最大値)
制約：パラメータに関する制約の記述。例えば、start_date は end_date と等しいか過去日でなければならないなど。

application/x-www-form-urlencoded (multipart/form-data) を指定する場合

パラメータの名前・値のセットを作成して POST してください。

application/json を指定する場合

パラメータの名前をプロパティとした JSON を作成して POST してください。

JSON

{
"api_user" : "smtp_api_user@example.com",
"api_key" : "a29yZWhhcGFzc3dvcmRkZXN1",
"to" : [
    {
    "name" : "Personal Name1",
    "address" : "user1@example.com"
    },
    {
    "name" : "Personal Name2",
    "address" : "user2@example.com"
    }
],
"from" : {
    "name" : "カスタマーサポート",
    "address" : "support@example.co.jp"
},
"subject" : "◯◯ショップ：会員登録完了通知",
"text" : "((#name#)) 様  この度は、....."
}

データ型

Email Sending API は以下の仕様に従い、データ型を取扱います。

データ型	説明
UTF-8	ASCIIを含むマルチバイト文字を表します。
ASCII	印刷可能なASCII文字を表します。
INTEGER	-2147483648 から 2147483647の範囲の数値を表します。
DATE	YYYY-MM-DD 形式で日付を表します。DD=99である場合、指定月の末日と解釈します。
TIME	HH:mm 形式で、時および分を24時間表記で表します。このAPIでは秒をリクエストパラメータとして取り扱う処理はありません。
DATETIME	YYYY-MM-DD HH:mm 形式で年月日および時分を表します。
BOOLEAN	true または false のいずれかを表します。

HTTPレスポンス

このセクションでは、Email Sending APIが送信するHTTPレスポンスの仕様について説明します。

ステータスコード

Email Sending APIは、以下のステータスコードを応答します。

コード	メッセージ	説明
200	OK	リクエストは正常に処理されました。
400	Bad Request	不正なパラメータがリクエストされたなどの理由により、リクエストは正常に処理されませんでした。
401	Unauthorized	ユーザ認証に失敗しました。
403	Forbidden	IP制限やアクセス制御により、ユーザからのリクエスト実行を拒否しました。
404	Not Found	リクエストされたURLは存在しません。
500	Internal Server Error	システム内部の問題により、リクエストを実行できませんでした。
503	Service Unavailable	アクセス数の超過やサーバの過負荷により、リクエストを実行できませんでした。

ヘッダ

Email Sending APIは、URLで指定されたフォーマットに従い、JSON または、XMLフォーマットのメッセージを応答します。これらの応答メッセージのフォーマットは、HTTPレスポンスヘッダ Content-Type により判別します。

Content-Type	説明
application/json	JSONフォーマットのメッセージを応答します。
application/xml	XMLフォーマットのメッセージを応答します。

メッセージ

Email Sending API は以下のメッセージを応答します。

成功

リクエストが成功した時に応答するメッセージについては、各API仕様の「レスポンス」を参照ください。

エラー

このメッセージは、リクエストが失敗した時に応答します。

JSONXML

{
    "errors" : [
        {
            "code" : "01-004",
            "field" : "api_user",
            "message" : "api_user is required."
        },
        {
            "code" : "01-004",
            "field" : "api_key",
            "message" : "api_key is required."
        }
    ]
}

<errors>
    <error>
        <code>01-004</code>
        <field>api_user</field>
        <message>api_user is required.</message>
    </error>
    <error>
        <code>01-004</code>
        <field>api_key</field>
        <message>api_key is required.</message>
    </error>
</errors>

エラーメッセージ

Email Sending APIの共通エラーメッセージを以下に説明します。共通エラーメッセージ以外にも、各APIごとに定義したエラーメッセージを応答することがあります。

コード	メッセージ（en）	メッセージ(ja)
01-001	System error was occurred. Please contact system administrator.	システムエラーが発生しました。システム管理者に連絡してください。
01-002	HTTP Request which use GET Method is not permitted. Please use POST Method.	GETメソッドを使用したHTTPリクエストは許可していません。POSTメソッドを使用してください。
01-003	User authentication was failed.	ユーザ認証に失敗しました。
01-004	{0} is required.	{0}は必須項目です。
01-005	The api_user does not have a role which is to perform requested process.	APIユーザーはリクエストされた処理を実行する権限がありません。
01-006	Connected IP does not allow to access API. Please confirm source IP setting.	接続IPはAPIにアクセスすることはできません。接続元IP設定を確認してください。
01-007	An error occurred when executing login.	ログインを実行するときにエラーが発生しました。
01-008	Invalid JSON format.	JSON形式が不正です。
01-009	Request data is invalid. Check the character code.	リクエストデータが不正です。文字コードを確認ください。
01-101	{0} was not found.	{0}が見つかりませんでした。
01-102	Server configuration is incorrect. Please contact system administrator.	サーバ設定が不正です。システム管理者にお問合せください。
02-001	{0} is required.	{0}は必須項目です。
02-002	Please enter a value more than {0} characters.	{0}文字以上の値を入力してください。
02-003	Please enter a value less than {0} characters.	{0}文字以下の値を入力してください。
02-004	Please enter a numeric value.	数値を入力してください。
02-005	Please enter a number in the range of {0} - {1}.	{0}-{1}の範囲の数値を入力してください。
02-006	Please enter only the alphabet, number and symbol characters.	英数字・記号のみを入力してください。
02-007	Please enter the date format (YYYY-MM-DD).	日付形式(YYYY-MM-DD)を入力してください。
02-008	{0} is invalid date.	{0}は不正な日付です。
02-009	Please enter the time format (HH:mm).	時刻形式(HH:mm)を入力してください。
02-010	{0} is invalid time.	{0}は不正な時刻です。
02-011	Please enter the date-time format (YYYY-MM-DD HH:mm).	日時形式(YYYY-MM-DD HH:mm)を入力してください。
02-012	{0} is invalid date-time.	{0}は不正な日時です。

セキュリティ

このセクションでは、Email Sending API のセキュリティについて説明します。

ユーザ認証

Email Sending API は、HTTPリクエストに含まれる api_user, api_key パラメータを使用したユーザ認証を行います。APIユーザの登録方法については、ユーザガイドの「APIユーザ」を参照ください。

メモ

Email Sending API は SMTP認証でユーザ認証するため、「SMTP」をチェックオンとする必要があります。