API Reference

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.

Credentials

All requests to our REST API need to be authenticated using HTTP Basic Authentication.

API Key API Secret
Username Password

One of the most common mistakes that is made with API keys is to inadvertently check them into public repositories on platforms such as GitHub. From these public repositories, fraudsters can search and steal your API access key and use it to send Spam messages and also drain your account balance. The main takeaway is don’t hard-code your API access key and don’t check it into a public code repository.

submit-message

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

 

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"}'

url = “https://API_KEY:API_SECRET@a2p.ameex-mobile.com/api/sms”
data = {
    “from”:”ABC”,
    “to”:”96650403020″,
    “content”:”Hello World”
}
res = requests.post(url,json=data)
res_json = res.json()
print(json.dumps(res_json))

Request-body (content-type: application/json)
Key Mandatory Accepted Format Description Example
from Yes

string

[A-Za-z0-9 ]{2,11}

SenderID ABC, ABC123
to Yes
[0-9]{10,15}
Receiver in E.164 Format 96650403020
content Yes string

SMS Content

it can include any unicode defined characters in UTF-8 format
concatenated message is supported

Hello Word
你好
مرحبا
base64url No 0 or 1

Content is base64url encoded.

this is recommended to avoid encoding issue for non-latin characters

(Default: 0)

1
udh No string User Data Header (Advance usage) 0003F90201

 

base64 encoded content: This is recommended to avoid encoding issue for non-latin characters.

Response-body
Key Description Example
message-count(integer) the count 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

Send 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'
}

Send 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

Use this API call to query SMS delivery status.

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

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"
}

url = f”https://{API_KEY}:{API_SECRET}@a2p.ameex-mobile.com/api/sms/{msgid}”

res = requests.get(url)

res_json = res.json()

print(json.dumps(res_json))

 

Path Parameters
Key Mandatory Description
msgid Yes the unique ID of a message

DLR Callback

A callback would be POST to your provided webhook when Delivery Receipt (DLR) is received from the carrier’s network. For security, you can whitelist traffic from only our IP address.

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) Sender ID ABC
msgid (string) The AMEEX ID for this message. HTTP-5C5CEFDC-EF700
status (string) DLR 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

Error Codes for SMS API

errorcode errormsg Note
1 Invalid API Key or Secret
2 missing parameter ‘from’, ‘to’, or ‘content’
3 B-number is invalid
4 SenderID 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

MNP Service

Only whitelisted IP is able to access this service.

Query EndPoint

http://mnp2.ameex-mobile.com/cgi-bin/mnp/get_mccmnc.fcgi

curl “http://mnp2.ameex-mobile.com/cgi-bin/mnp/get_mccmnc.fcgi?msisdn=6581101234

response:
{
“status”: 0,
“msg”: “OK”,
“mccmnc”: “52505”,
“msisdn”: “6581101234”,
}

url = f”http://mnp2.ameex-mobile.com/cgi-bin/mnp/get_mccmnc.fcgi?msisdn={msisdn}”

res = requests.get(url)

res_json = res.json()

print(json.dumps(res_json))

Response-body
Key Description Example
msisdn B-number 6581101234
mccmnc MCCMNC of the requested B-number

52505

00000 (when no IMSI returned)

error Error returned from HLR unknownSubscriber
status indicate if a request is accepted
 0
-1
msg indicate if a request is accepted, explain the error when it’s not accepted

OK (when status=0)

Invalid MSISDN (when status=-1)

Error Codes for MNP

status description msg
0 indicate request is accepted OK
-1 indicate request is not accepted

Missing Parameter

MSISDN format wrong

Destination not supported

 

Example when HLR lookup return error without IMSI

{
    "status": 0,
    "msg": "OK",
    "mccmnc": "00000",
    "msisdn": "XXXXXXXXXXXX",
    "error": "absentSubscriber"
}

{
    "status": 0,
    "msg": "OK",
    "mccmnc": "00000",
    "msisdn": "XXXXXXXXXXXX",
    "error": "unknownSubscriber"
}

{
    "status": 0,
    "msg": "OK",
    "mccmnc": "00000",
    "msisdn": "XXXXXXXXXXXX",
    "error": "teleserviceNotProvisioned"
}