AEROSMS API は REST を基本に構成し、SMS送信やSMS送信ステータスなど、外部のプログラムから AEROSMS の機能を簡単に使用することを可能にしています。
AEROSMS API は、リクエスト、レスポンスおよびエラー含め、すべて、JSON 形式でやりとりを行います。
AEROSMS API は、RAML (RESTful API Modeling Language) をもとに、設計・管理を行っています。
RAMLはRESTful APIを設計するための定義を YAML ベースでまとめた仕様となっているため、プログラム的にAPI設計を簡易に読み出すことができます。
- #%RAML 0.8
- title: AEROSMS API
- baseUri: https://aerosms.net/api/{version}
- version: v1
- mediaType: application/json
- /message:
- /send:
- post:
- description: "1つの宛先に対して、SMSを送信する"
- body:
- application/json
- schema: sendRequest
- example: |
- {
- "email": "example@aerosms.net"
- "apikey": "5b8f2433314f1c04e4fb8821c1a0ad78",
- "message": "1宛先送信テストです。",
- "label": "○月○日:送信テスト",
- "to": [
- {
- "number": "090-1234-5678",
- "tags": [ "customer", "123" ]
- }
- ]
- }
- responses:
- 200:
- body:
- application/json:
- schema: sendResponse
- example: |
- {
- "id": 101,
- "status": "sent",
- "message": "1宛先送信テストです。",
- "label": "○月○日:送信テスト",
- "created_at": "2016-04-01 09:00:00",
- "send_at": "2016-04-01 09:00:01",
- "sent_at": "2016-04-01 09:00:04",
- "duration": "3",
- "expires_at": "2016-04-01 09:00:10",
- "to": [
- {
- "id": 201,
- "number": "09012345678",
- "tags": [ "customer", "123" ]
- }
- ]
- }
- 400:
- body:
- application/json:
- schema: !include message.json
- schemas:
- - sendRequest: |
- {
- "description": "SMS送信用データ",
- "type": "object",
- "properties": {
- "email": {
- "description": "AEROSMSのログインメールアドレス",
- "type": "string",
- "required": true
- },
- "apikey": {
- "description": "APIキー",
- "type": "string",
- "required": true
- },
- "message": {
- "description": "送信するメッセージ",
- "type": "string",
- "required": true,
- "maxLength": 70,
- "minLength": 1
- },
- "label": {
- "description": "本SMS送信に関するラベル",
- "type": "string",
- "required": false,
- "maxLength": 255
- },
- "to": [
- {
- "number": {
- "description": "宛先の携帯番号",
- "type": "string",
- "required": true,
- "pattern": "[090|080|070][\-\d{4}\-\d{4}|\d{8}]"
- },
- "tags": [
- "description": "宛先に設定するタグ文字列",
- "type": "string",
- "required": false
- "maxLength": 255
- ],
- "register": {
- "description": "AEROSMSに宛先を登録するか否か",
- "type": "boolean",
- "required": false,
- "default": true
- }
- }
- ],
- "expires": {
- "description": "SMS送信期限(秒)、送信期限がきたらステータスはfailedとなる",
- "type": "integer",
- "minimum": 8,
- "maximum": 16,
- "required": false,
- "default": 10
- },
- "retry": {
- "description": "リトライ回数、ステータスがfailedになった時点でリトライ開始",
- "type": "integer",
- "minimum": 1,
- "maximum": 3,
- "required": false,
- "default": false
- },
- "callback": {
- "description": "SMS送信結果を受け取るコールバックURL、初回送信およびステータスがsent/failedになった時点でコールバック",
- "type": "string",
- "required": false,
- "pattern": "https?://[\w/:%#\$&\?\(\)~\.=\+\-]+",
- "maxLength": 1024
- },
- "dryrun": {
- "description": "SMS送信が正しく実行されるかの検査(実際にはSMS送信されません)",
- "type": "boolean",
- "required": false,
- "default": false
- }
- }
- }
- }
- - sendResponse: |
- {
- "description": "SMS送信後の返却データ",
- "type": "object",
- "properties": {
- "id": {
- "description": "SMS送信時のAEROSMSが管理するID",
- "type": "integer"
- },
- "code": {
- "description": "SMS送信時のステータスコード",
- "type": "integer",
- "enum": [ 200, 400 ]
- },
- "status": {
- "description": "SMS送信時のステータス",
- "type": "string",
- "enum": [ "pending", "sent", "queued", "failed" ]
- },
- "message": {
- "description": "送信したメッセージ",
- "type": "string"
- },
- "label": {
- "description": "本SMS送信に関するラベル",
- "type": "string"
- },
- "created_at": {
- "description": "送信受付日時",
- "type": "string"
- },
- "send_at": {
- "description": "送信開始日時",
- "type": "string"
- },
- "sent_at": {
- "description": "送信完了日時",
- "type": "string"
- },
- "duration": {
- "description": "送信所要時間(秒)",
- "type": "string"
- },
- "expires_at": {
- "description": "送信期限",
- "type": "string"
- },
- "failed_at": {
- "description": "送信失敗日時",
- "type": "string"
- },
- "to": [
- {
- "id": {
- "description": "送信した宛先をAEROSMSが管理するID",
- "type": "integer"
- },
- "number": {
- "description": "送信した宛先の携帯番号",
- "type": "string",
- "pattern": "\d{11}",
- },
- "tags": [
- "description": "送信した宛先に設定したタグ文字列",
- "type": "string"
- ],
- "register": {
- "description": "AEROSMSに宛先を登録するか否か",
- "type": "boolean"
- }
- }
- ],
- "retry": {
- "description": "リトライ回数",
- "type": "integer"
- },
- "callback": {
- "description": "SMS送信結果を受け取るコールバックURL",
- "type": "string"
- },
- "dryrun": {
- "description": "SMS送信が正しく実行されるかの検査(実際にはSMS送信されません)",
- "type": "integer"
- },
- }
- }
- }
AEROSMS API で返却するメッセージの仕様です。
すべて、JSON 形式で返却されます。
以下は、300 のメッセージが返却された例です。
{"code":300,"message":{"en":"Mobile number is not correct","ja":"\u9001\u4fe1\u5148\u306e\u643a\u5e2f\u756a\u53f7\u304c\u6b63\u3057\u304f\u3042\u308a\u307e\u305b\u3093"}}
- 200:
- ja: SMS送信に成功しました
- en: SMS transmission succeeded
- 201:
- ja: SMS送信のドライランに成功しました
- en: SMS transmission succeeded by dryrun
- 300:
- ja: 送信先の携帯番号が正しくありません
- en: Mobile number is not correct
- 301:
- ja: 送信メッセージの文字数が上限を超えています
- en: The number of characters in the message exceeds the limit
- 302:
- ja: 通数の上限を超えています
- en: Exceeded the limit on the number of SMS transmission
- 400:
- ja: SMS送信に失敗しました
- en: SMS transmission failed
- 401:
- ja: 認証が必要です
- en: Unauthorized
- 402:
- ja: SMS送信がタイムアウトしました
- en: SMS transmission has timed out
- 403:
- ja: データベースエラー
- en: Database Error
- 404:
- ja: ファイルシステムエラー
- en: Filesystem Error
- 405:
- ja: 不明なエラーです
- en: Unknown Error
- 406:
- ja: 送信期限までのSMS送信に失敗しました
- en: SMS transmission failed until deadline