Welcome

MessageHub SMS API you can send SMS messages to 7+ billion subscribers of 1000+ Mobile Operators in 200+ countries.

SMS API is based on REST. It uses built-in HTTP authentication and HTTP status codes. All data exchange is done in JSON format.

To test MessageHub SMS API, you will need a valid API account. If you don't have one yet please register your account.

Examples

Authentication Endpoint

https://app.messagehub.nl/apis/auth/

SMS API Endpoint

https://app.messagehub.nl/apis/sms/mt/v2/

Authentication


Each request must be accompanied by a valid access_token. access_token are generated upon successful authentication. To authenticate you must send an auth request.

https://app.messagehub.nl/apis/auth/

This request accepts parameters type with value access_token, username and password.

access_token


If the request succeeded, an authentication object is returned, which includes an access_token and a refresh_token. Otherwise, an error is returned. access_token grants you access to make requests.

Setup the Authorization HTTP header with your access_token. Authorization:Bearer dcec4eb6-035c-41a4-9871-82c5bd3ef379

access_token is valid for 30 minutes, after which it expires. To preserve connection you must either refresh with refresh_token or reset connection and request a new access_token.

refresh_token


To refresh connection you must send an auth request.

https://app.messagehub.nl/apis/auth/

This request accepts parameters type with value "refresh_token", refresh_token with value the refresh token, provided by a previously successful auth request.

Examples

Authentication

POST https://app.messagehub.nl/apis/auth/
Request Definition 

POST https://app.messagehub.nl/apis/auth/
Content-Type : application/json
{
"type" : "access_token",
"username" : "myusername",
"password" : "mypassword"
}
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
"validity_period" : 1800,
"refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
}
}
Example Response

Refresh Connection


POST https://app.messagehub.nl/apis/auth
Content-Type : application/json
{
"type" : "refresh_token",
"refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641",
}
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"access_token" : "0e3f6ecb-7a7e-4d03-a004-d710db8978ab",
"validity_period" : 1800,
"refresh_token" : "ecbb4d30-6da2-4b78-998e-d01025c648f2"
}
}
Example Response

Send Single SMS


To send an sms you must send a send POST request.

https://app.messagehub.nl/apis/sms/mt/v2/send/

Set parameters to with the the recipient mobile number phone in international E.164 format and from with your preferred sender.

Finally, setup parameter message with your message text.

Remember to setup the Authorization HTTP header with your access_token

Congratulations! You just sent your first SMS using the SMS API.

If the request succeeded, an object is returned, which includes submission status, message id, type of message and the initial cost of the sms message. (Notice: the initial cost is calculated based on the prefix of the recipient's number. Final cost is calculated when the SMS is sent by the platform, where more advanced identification processes are used ) Otherwise, an error is returned.

Examples

Send Simple SMS

POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Request Definition 

POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Content-Type : application/json
[
{
"to" : ["447945223343"],
"from" : "HelloWorld",
"message" : "My first SMS message."
}
]
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : [
{
"status" : "submitted",
"id" : 543521789981,
"to" : "447945223343",
"from" : "HelloWorld",
"message" : "My first SMS message.",
"operator_id" : 765,
"cost" : "0.0400"
}
]
}
Example Response

Multilingual Support


POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Content-Type : application/json
[
{
"to" : ["8613054782931"],
"from" : "HELLO",
"message" : "早上好我的朋友"
}
]
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : [
{
"status" : "submitted",
"id" : 543521789982,
"to" : "8613054782931",
"from" : "HELLO",
"message" : "早上好我的朋友",
"operator_id" : 765,
"cost" : "0.0400"
}
]
}
Example Response

Send Multiple SMS


To send multiple sms you must send a send POST request.

https://app.messagehub.nl/apis/sms/mt/v2/send/

Set parameters message with your message text and from with your preferred sender.

Now, set parameter to with an array of the recipient mobile numbers in international E.164 format.

In this request, body is enclosed in an array. Repeat adding objects to send SMS with different messages and/or senders to multiple recipients.

Remember to setup the Authorization HTTP header with your access_token

Congratulations! You just sent multiple SMS using one request.

If the request succeeded, a response object is returned, which includes id, broadcast_date, expiration_date, and the cost of the sms. Otherwise, an error is returned.

Examples

Send Multiple SMS


POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Content-Type : application/json
[
{
 "to" : ["447945223343"],
 "from" : "OTP PIN",
 "message" : "Your one time pin is: 875529"
},
{
 "to" : ["447945223342","447945223341"],
 "from" : "Alert",
 "message" : "A product in your watchlist is on discount. For more
 information click here: http://bit.ly/1jL3YEw"
}
]
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : [
{
"status" : "submitted",
"id" : 543521789995,
"to" : "447945223343",
"from" : "OTP PIN",
"message" : "Your one time pin is: 875529",
"operator_id" : 765,
"cost" : "0.0400"
},
{
"status" : "submitted",
"id" : 543521789996,
"to" : "447945223342",
"from" : "Alert",
"message" : "A product in your watchlist is on discount. For
more information click here: http://bit.ly/1jL3YEw",
"operator_id" : 765,
"cost" : "0.0400"
},
{
"status" : "submitted",
"id" : 543521789997,
"to" : "447945223341",
"from" : "Alert",
"message" : "A product in your watchlist is on discount. For
more information click here: http://bit.ly/1jL3YEw",
"operator_id" : 765,
"cost" : "0.0400"
}
]
}
Example Response

Send WAP Push


To send a WAP Push you must send a send POST request.

https://app.messagehub.nl/apis/sms/mt/v2/send/

Set parameters to with the the recipient mobile number phone in international E.164 format and from with your preferred sender.

Setup parameter wap_title with your preferred title.

Setup parameter wap_url to your resource URI (image / document /video etc) location.

Finally, setup message_type with value "wap_push"

Remember to setup the Authorization HTTP header with your access_token

Congratulations! You just sent a WAP Push using the SMS API.

If the request succeeded, an object is returned, which includes submission status, message id, type of message and the initial cost of the sms message. (Notice: the initial cost is calculated based on the prefix of the recipient's number. Final cost is calculated when the SMS is sent by the platform, where more advanced identification processes are used ) Otherwise, an error is returned.

Examples

Send WAP Push

POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Request Definition 

POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Content-Type : application/json
[
{
   "to" : ["447945223343"],
   "from" : "Purchase",
   "wap_title" : "Your purchase link",
   "wap_url" : "http://bit.ly/1Rmmw1b",
   "message_type" : "wap_push"
}
]
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : [
{
  "status" : "submitted",
  "id" : 543521790030,
  "to" : "447945223343",
  "from" : "Purchase",
  "wap_title" : "Your purchase link",
  "wap_url" : "http://bit.ly/1Rmmw1b",
  "operator_id" : 765,
  "cost" : "0.0400"
}
]
}
Example Response

Send Flash SMS


To send a Flash SMS you must send a send POST request.

https://app.messagehub.nl/apis/sms/mt/v2/send/

Set parameters to with the the recipient mobile number phone in international E.164 format and from with your preferred sender.

Setup parameter message with your message text.

Finally, setup message_type with value "flash"

Remember to setup the Authorization HTTP header with your access_token

Congratulations! You just sent a flash SMS using the SMS API.

If the request succeeded, an object is returned, which includes submission status, message id type of message and the initial cost of the sms message. (Notice: the initial cost is calculated based on the prefix of the recipient's number. Final cost is calculated when the SMS is sent by the platform, where more advanced identification processes are used ) Otherwise, an error is returned.

Examples

Send Flash SMS

POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Request Definition 

POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Content-Type : application/json
[
{
   "to" : ["447945223343"],
   "from" : "HelloWorld",
   "message" : "My first SMS message.",
   "message_type" : "flash"
}
]
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : [
{
  "status" : "submitted",
  "id" : 543521789981,
  "to" : "447945223343",
  "from" : "HelloWorld",
  "message" : "My first SMS message.",
  "operator_id" : 765,
  "cost" : "0.0400"
}
]
}
Example Response

URL Tracking And Shortening


You can track URL links conversion contained in SMS messages.

As soon as a user clicks a link, CTR, platform, operating system, browser, mobile number and network information is forwarded automatically, to your system / platform.

Setup parameter track_url with value "1"

Remember to setup the Authorization HTTP header with your access_token

Congratulations! Our system will automatically shorten and setup tracking for URL.

If the request succeeded, an object is returned, which includes submission status, message id, type of message and the initial cost of the sms message. (Notice: the initial cost is calculated based on the prefix of the recipient's number. Final cost is calculated when the SMS is sent by the platform, where more advanced identification processes are used ) Otherwise, an error is returned.

Examples

URL Tracking And Shortening

POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Request Definition 

POST https://app.messagehub.nl/apis/sms/mt/v2/send/
Content-Type : application/json
[
{
   "to" : ["447945223343"],
   "from" : "ShopTop",
   "message" : "20% off purchases made
   today: http://www.eshoptopcommerce.com/store/products
   /SDi9jdq0dhq0.html",
   "track_url" : 1,
   "message_type" : "sms"
}
]
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : [
{
  "status" : "submitted",
  "id" : 543521790030,
  "to" : "447945223343",
  "from" : "ShopTop",
  "message" : "20% off purchases made today: m9p.co/DF65t4s1",
  "track_url" : 1,
  "url" : "http://www.eshoptopcommerce.com/store/products
  /SDi9jdq0dhq0.html",
  "operator_id" : 765,
  "cost" : "0.0400"
}
]
}
Example Response

Receive Delivery Reports


Delivery reports are forwarded automatically, to the user system / platform. When an SMS delivery report is received by our SMS API Platform, the DLR information is immediately forwarded to your specified DLR Callback URL via a POST request. Data are transmitted in JSON format.

You can setup your DLR Callback URL in the web portal.

https://[DLR Callback URL]

DLR forwarding POST request transmits the message id ( cross-check with message id returned from send POST requests ), recipient phone, delivery status, delivery date, final cost, network operator id of the recipient phone and reference id / custom data of the message submission. Otherwise, an error is returned.

SMS API Platform will stop sending DLR information of a SMS when it accepts a HTTP Status Code 200 from the user’s system. HTTP Status Code 200 is considered as a valid acknowledgement of DLR information from the user side.

SMS API Platform will send out DLR based on the following schedule:

ATTEMPT TIME
First Instantly
Second After 5 minutes
Third After 15 minutes
Fourth After 30 minutes
Fifth After 1 hour
Sixth After 5 hours
Seventh After 24 hours

At this point, if the user system still fails to acknowledge DLR information, there will be no more attempts to transmit and information will be discarded.

There are multiple delivery status codes:
CODE STATUS
0 No Status
1 Delivered
2 Failed / Erroneous Number
3 Failed / Network Error
4 Pending
5 Expired

Examples

Receive Delivery Reports


POST https://[DLR Callback URL]
Content-Type : application/json
{
 "id" : 543521789981,
 "phone" : "447945223343",
 "status" : 1,
 "date" : "2014-09-02 09:37:31",
 "cost" : "0.067",
 "operator_id" : 473,
 "reference_code" : "FH832JR0REW1F0"
}
Example Request 
HTTP/1.1 200 OK
Example Response

Receive URL Tracking And Conversion Information


URL tracking information is forwarded automatically, to the user system / platform. When a user clicks a link, the CTR and user information is immediately forwarded to your specified Callback URL via a POST request. Data are transmitted in JSON format.

You can setup your Callback URL in the web portal

https://[DLR Callback URL]

URL Tracking POST request transmits the message id ( cross-check with message id returned from send POST requests ), recipient phone, url open date the url tracked, user_agent (includes platform, device, operating system, browser etc.), message information and network operator information. Otherwise, an error is returned.

SMS API Platform will stop sending URL tracking information of a SMS when it accepts a HTTP Status Code 200 from the user’s system. HTTP Status Code 200 is considered as a valid acknowledgement of URL information from the user side.

SMS API Platform will send out URL tracking information based on the following schedule:

ATTEMPT TIME
First Instantly
Second After 5 minutes
Third After 15 minutes
Fourth After 30 minutes
Fifth After 1 hour
Sixth After 5 hours
Seventh After 24 hours

At this point, if the user system still fails to acknowledge URL information, there will be no more attempts to transmit and information will be discarded.

Examples

URL Tracking Information


POST https://[Callback URL]
Content-Type : application/json
{
 "id" : 543521789981,
 "phone" : "447945223343",
 "url" : "http://www.eshoptopcommerce.com/store/products
 /SDi9jdq0dhq0.html",
 "user_agent" : "Mozilla/5.0 (iPhone; CPU iPhone OS 9_1
 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile
 /13B143 Safari/601.1",
 "date" : "2015-10-12 13:21:12",
 "sender" : "ShopTop",
 "message" : "20% off purchases made today: m9p.co/DF65t4s1",
 "operator" : "T-Mobile UK",
 "mcc" : "234",
 "mnc" : "30"
}
Example Request 
HTTP/1.1 200 OK
Example Response

Get Balance


To get your account's balance you must send a balance GET request.

https://app.messagehub.nl/apis/sms/mt/v2/balance/

Remember to setup the Authorization HTTP header with your access_token

If the request succeeded, an object is returned, which includes your account balance. Otherwise, an error is returned.

Examples

Get Balance

GET https://app.messagehub.nl/apis/sms/mt/v2/balance/
Request Definition 

GET https://app.messagehub.nl/apis/sms/mt/v2/balance/
Content-Type : application/json
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
  "balance" : "7845.3500"
}
}
Example Response

Get Pricing


To get your account’s pricing details and covered networks, you must make a pricing GET request.

https://app.messagehub.nl/apis/sms/mt/v2/pricing/

Remember to setup the Authorization HTTP header with your access_token

If the request succeeded, an object is returned, which includes your account currency and an array of network objects with coverage and pricing information. Network objects have attributes operator id, operator countryname, operatorname, operator mobile country code mcc, operator network mobile code mnc and your account price per SMS sent to this network. Otherwise, an error is returned.

Examples

Get Pricing

GET https://app.messagehub.nl/apis/sms/mt/v2/balance/
Request Definition 

GET https://app.messagehub.nl/apis/sms/mt/v2/pricing/
Content-Type : application/json
Example Request 

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"currency" : {
  "name" : "Euro",
  "symbol" : "EUR"
},
"pricing" : [
 {
    "id" : 473,
    "countryname" : "Afghanistan",
    "operatorname" : "Roshan",
    "mcc" : "412",
    "mnc" : "020",
    "price" : "0.0190"
 },
 ..............
]
}
}
Example Response

Errors


SMS API uses 2 levels of errors. Conventional HTTP status codes and application error codes.

SMS API raises errors for many reasons (authentication, invalid parameters, network / server errors etc.). Consult the detailed HTTP status codes and application error codes tables for detailed explanation of response codes.

Application Errors


SMS API returns errors in an array of objects.
CODE numeric MESSAGE string
Application error code identifying error. A human-readable message providing more details about the error.

Examples

Errors


{
"status_code" : 404,
"status_message" : "Not found",
"errors" : [
{
  "code" : 1007,
  "message" : "URI not found"
}
]
}
Example Response

HTTP Status Codes

code# STATUS MESSAGE
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to invalid JSON format.
401 Unauthorized No valid API key provided.
404 Not Found The requested resource doesn't exist.
422 Unprocessable Request The request unprocessable, often due to invalid parameters.
500 Internal Server Error The service is temporarily unavailable.

Application Error Codes

code# STATUS MESSAGE
1001 Invalid token type Invalid parameter.
1002 Invalid username Invalid parameter.
1003 Invalid password Invalid parameter.
1004 Invalid authentication credentials Credentials provided is not correct.
1005 Invalid refresh token Invalid parameter.
1006 Insufficient balance User balance is not enough in order to process the request.
1007 URI not found Request URI not found.
1009 Invalid access token Access token is invalid.
1101 Invalid JSON format Invalid JSON structure.
1200 Invalid parameter (from) Invalid parameter. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-) or 14 numeric characters (0-9). Special characters are not allowed.
1201 Invalid Parameters List Parameter list is malformed.
1202 Invalid message Invalid parameter.
1203 Invalid parameter (to) Invalid parameter.
1204 SMS unavailable Your account does not have permissions to use SMS service.
1205 Invalid receive_dlr Invalid parameter.
1206 Invalid message_type Invalid parameter.
1207 Invalid wap_title Invalid parameter.
1208 Invalid track_url Invalid parameter.
1209 Invalid wap_url Invalid parameter.
1213 Invalid udd Invalid parameter.
1214 Invalid udh Invalid parameter.
1215 Invalid schedule_date Invalid parameter.
1216 Invalid schedule_date schedule_date must be at least 20 minutes from now.
1217 Invalid expire_date Invalid parameter.
1218 Invalid expire_date Eexpire_date must be 30 minutes from schedule_date.
1219 Invalid expire_date expire_date must be 30 minutes from now.
1221 Invalid phone (MSISDN) No valid API key provided.
1222 Service is not available Service is temporarily unavailable.
1223 Error submitting SMS Service is temporarily unavailable.