REST API

Overview

REST API can be used to send all types of SMS and check delivery status.
Delivery status can also be pushed to client's WebHook (HTTP(S) callback).
Numbers are specified in E.164 format.
HTTP Request body and response use JSON format.
Each request requires a BASIC authentication.

Download OpenAPI 3 Definition

smsapi.yaml
smsapi.json
check API on SwaggerHub.

API endpoint

https://a2p.ameex-mobile.com/api

submit-message

Send an outbound message from your AMEEX account
POST https://API_KEY:API_SECRET@a2p.ameex-mobile.com/api/sms

Request-body (content-type: application/json)

Key	Description	Example	Default
from* (string)	senderID of a message	ABC, ABC123	none
to* (string)	receipient of a message. Numbers are specified in E.164 format	96650403020	none
content* (string)	The body of the message being sent it can include any unicode defined characters in UTF-8 format concatenated message is supported	Hello Word 你好 مرحبا	none
base64url (integer)	set to 1 if :content is base64url encoded this is recommended to avoid encoding issue for non-latin characters	1	0
udh (string)	Advanced usage: your custom Hex encoded User Data Header	0003F90201	None

* are required parameters

Response

Key	Description	Example
message-count (integer)	the amount of messages submitted	1
messages (object)	An Object contains messageID and recipient of the message just submitted. If it’s a concatenated message, there will be multiple objects returned	[ { msgid: HTTP-5C5CEFDC-EF700, to:96650403020 }, { msgid: HTTP-5C5CEFDC-EF701, To:96650123456 } ]
errorcode	response of the submit-message request 0 means successful, non 0 means failure, refer to errorcode list for failure reasons	0
errormsg	Meaning of the error	B-number invalid

Examples

A. Short message (single-part)


curl -X POST "https://API_KEY:API_SECRET@a2p.ameex-mobile.com/api/sms" \
-H "accept: application/json" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"from":"ABC","to":"96650403020","content":"Hello World"}'

response:
{
          'errorcode' => '0',
          'message-count' => '1',
          'messages' => [
                          {
                            'to' => '+96650403020',
                            'msgid' => 'HTTP-5C5D9765-94410'
                          }
                        ]
}

B. Concatenated message (multi-part)


curl -X POST "https://API_KEY:API_SECRET@a2p.ameex-mobile.com/api/sms" \
-H "accept: application/json" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"from":"ABC","to":"96650403020","content":"This message is a concatened text \
 SMS with extended characters with [AMEEX] written into square brackets in the \
 first part of this message to check proper concatened sms including extended characters \
  and [AMEEX] written into curly brackets END"}'

response:
{
          'messages' => [
                          {
                            'msgid' => 'HTTP-5C5D9706-10000',
                            'to' => '+96650403020'
                          },
                          {
                            'to' => '+96650403020',
                            'msgid' => 'HTTP-5C5D9706-11001'
                          }
                        ],
          'message-count' => '2',
          'errorcode' => '0'
}

C. message including non-Latin characters (e.g كلمة), base64url the content to be "2YPZhNmF2Kk"


curl -X POST "https://API_KEY:API_SECRET@a2p.ameex-mobile.com/api/sms" \
-H "accept: application/json" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"from":"ABC","to":"96650403020","content":"2YPZhNmF2Kk","base64url":"1"}'

response:
{
          'errorcode' => '0',
          'message-count' => '1',
          'messages' => [
                          {
                            'to' => '+96650403020',
                            'msgid' => 'HTTP-5C5D9765-94410'
                          }
                        ]
}

query-delivery-status

Query message delivery status
GET https://API_KEY:API_SECRET@a2p.ameex-mobile.com/api/sms/:msgid

Path Parameters

Key	Description
msgid* (string)	the unique ID of a message, which is returned by server after submitting a message

Examples


curl "https://API_KEY:API_SECRET@a2p.ameex-mobile.com/api/sms/HTTP-5C5CEFDC-EF700"


response:
{
   "msisdn": "96650403020",
   "to": "ABC",
   "msgid": "HTTP-5C5CEFDC-EF700",
   "status": "delivered",
   "errorcode": 0,
   "dlr-timestamp": "2001010100",
   "timestamp": "2020-01-01 01:00:00"
}

Callback

When we receive delivery status from end operator, we will post it to the webhook provided by client.
POST http://example.com/callback

Request-body (content-type: application/json)

Key	Description	Example
msisdn (string)	The recipient of the message was sent to (E.164 format)	96650403020
to (string)	The SenderID set in “from” parameter in submit-message request.	ABC
msgid (string)	The AMEEX ID for this message.	HTTP-5C5CEFDC-EF700
status (string)	Delivery Status	DELIVRD EXPIRED UNDELIV REJECTD UNKNOWN
dlr-timestamp (string)	When the DLR was recieved from the carrier in the following format YYMMDDHHMM.	2001010100 (means 2020-01-01 01:00)
timestamp	Timestamp (in GMT) when AMEEX push this delivery receipt to your webhook end point.	2020-01-01 01:00:00

Errors

List of error codes.

Error Code	Text	Note
1	you are not authorized, please check api_key and api_secret
2	missing parameter 'from', 'to', or 'content'
3	B-number is invalid
4	TPOA/Sender length is too long	max length 12 characters
10	Message ID not found	It’s response for query-delivery-status
1001	Internal Error, please contact support@ameex-mobile.com
1002	Internal Error, please contact support@ameex-mobile.com

Useful Resources

Base64url

Most modern language has module for base64url.
Example: base64url.encode in javascript, encode_base64url in perl

ngrok

https://ngrok.com/
When client implements callback url, it’s often on local development server and not publicly accessable.
So how can you test the notification sent from outside service into your local application?
Ngrok can be of help. It will create a secure tunnel from the internet to your locally-running application.

Basic Authentication

https://swagger.io/docs/specification/authentication/basic-authentication/

Try the API


curl -X POST "https://api_key:api_secret@virtserver.swaggerhub.com/v897/sms/1.0.0/sms" \
-H "accept: application/json" -H "Content-Type: application/json; charset=utf-8" \
-d '{"from":"ABC","to":"96650403020","content":"Hello World"}'


curl -X POST "https://API_KEY:API_SECRET@a2p.ameex-mobile.com/api/sms" \
-H "accept: application/json" -H "Content-Type: application/json; charset=utf-8" \
-d '{"from":"ABC","to":"96650403020","content":"Hello World"}'