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]

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

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

sandbox

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

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

transactional-email

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

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

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

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

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

認証

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


HTTPリクエスト

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

メソッド

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

ヘッダ

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

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

コンテンツタイプ

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

パラメータ

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

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

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

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


データ型

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仕様の「レスポンス」を参照ください。

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

JSON

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

XML

<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-004 {0} is required. {0}は必須項目です。

セキュリティ

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

ユーザ認証

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

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