Email Sending API

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


API仕様

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

バージョン1

最新の機能を提供するバージョンです。


共通仕様

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

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

接続先ホストとURL

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

Email Sending API は、SMTPと同様にメールサーバーが機能を提供します。 サービスプランにより接続先ホストを以下の通り指定してください。

Standard

sandbox

無料トライアルでは、sandboxと呼ぶ MTAクラスタを利用することができ、以下のエンドポイントに接続することができます。

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

transactional-email

有料プランでは、transactional-email と呼ぶ MTAクラスタを利用することができ、以下のエンドポイントに接続することができます。

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

Pro

占有利用が可能なマネージド型メール配信プラットフォームを提供しており、以下のエンドポイントに接続することができます。

項目 値                 
エンドポイントURL https://SUBDOMAIN.smtps.jp/v1/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 リクエストは正常に処理されました。
204 No Content リクエストは正常に処理されたが、対象データが存在しなかった。例えば、メールアドレスを検索キーとして検索処理を実行したが該当するデータが存在しなかった場合、ステータスコード204を応答します。
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 は以下のメッセージを応答します。

このメッセージは、add / edit / delete などデータ編集を行うリクエストが成功した時に応答します。

JSON

{
    "message" : "User example1.hde was deleted"
}

XML

<message>User example1@hde.co.jp was deleted<message>

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

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」をチェックオンとする必要があります。