Create a new brand, Start your business now!

Learn how to publish and retrieve data from SMS123.net by using our API integration

Introduction

The API we provide programmatic access to SMS123 features and data. In designing the API, our goal was to make it simple, intuitive, and predictable. The standards used in this API are widely accepted standards such as using POST to access the API and XML format for the returned data.
We use POST HTTP request instead of GET is because it has no restrictions on data length. Thus, the output can contain long sentences that returned by the API.
POST supports binary data type as well. Hence the possibilities of user uploading images to change their logo.
For security concern, POST is a little safer because the parameters are not stored in browser history and web server logs unlike GET.
By using POST, the URL will remain clean because the data will not be displayed in URL.

GET method send SMS

https://www.sms123.net/api/send.php?apiKey=[APIKEY]&recipients=[RECIPIENTS]&messageContent=[MESSAGE]&referenceID=[CUSTOMREFERENCEID]

[APIKEY] API Key. (Find your API key at www.sms123.net My Account > Settings)
[RECIPIENTS] Recipient mobile number.
- Mobile number with country code.
- Once recipient one request.
- One recipient one request.
- You can use semi-colon(;) to separate each recipient without space when sending multiple recipients.
[MESSAGE] Message body.
- A single SMS may contain 160 characters, or 70 characters for Unicode.
- Concatenated SMS may contains 152 characters, or 63 characters for Unicode.
- All Malaysia mobile number will be minus 4 characters “RM0 ” at the beginning of each SMS content.
- Maximum of 10 concatenated SMS.

As per SKMM guidelines, you shall include price information at the beginning of each SMS. You shall use either “Free msg/RM0/Msj ini percuma” at the beginning of the SMS content. For more information, please read our Terms & Conditions.
[CUSTOMREFERENCEID] An unique reference id from your system to avoid duplicate request.
[STATUS] Show the status for send SMS (ok / error)
[MSGCODE] Show code to represent particular status.
[REFERENCEID] Your reference for any future enquiries.
[BALANCE] Your account current balance.
[DATA] Each recipient sending reference ID.


Request and Response format


Encourage to use URL encode on the request link / url to converts reserved, unsafe, and non-ASCII characters in URLs to a format that is universally accepted and understood by all web browsers and servers. Paste it here and encode link
Please refer to here to know more about url encoding characters reference

Request

https://www.sms123.net/api/send.php?apiKey=[APIKEY]&recipients=[RECIPIENT]&messageContent=[MESSAGE]&referenceID=[CUSTOMREFERENCEID]

Encoded Request

https%3A%2F%2Fwww.sms123.net%2Fapi%2Fsend.php%3FapiKey%3D %5BAPIKEY%5D%26recipients%3D%5BRECIPIENT%5D%26messageContent%3D %5BMESSAGE%5D%26referenceID%3D%5BCUSTOMREFERENCEID%5D

Response

{"status":"[STATUS]","msgCode":"[MSGCODE]","statusMsg":"[ STATUSMSG]","referenceID":"[ REFERENCEID]"," balance":"[ BALANCE]", "data": "[DATA]" }

*Response array encoded with JSON

Example code for request and response


Request

  • Single recipient
    https://www.sms123.net/api/send.php?apiKey=22f277843206d477d3cd4ae1c9220bc3&messageContent=Testing%123&recipients= 6010xxxxxxx&referenceID=ba63ht12opab6

  • Multiple recipients
    https://www.sms123.net/api/send.php?apiKey=22f277843206d477d3cd4ae1c9220bc3&messageContent=Testing%123&recipients= 6010xxxxxxx;6012xxxxxxx&referenceID=iyr340hbc6ja0b

Encoded Request

  • Single recipient
    https%3A%2F%2Fwww.sms123.net%2Fapi%2Fsend.php%3F apiKey%3D22f277843206d477d3cd4ae1c9220bc3%26messageContent%3D Testing%25123%26recipients%3D6010xxxxxxx%26referenceID%3Dba63ht12opab6

  • Multiple recipients
    https%3A%2F%2Fwww.sms123.net%2Fapi%2Fsend.php%3F apiKey%3D22f277843206d477d3cd4ae1c9220bc3%26messageContent%3D Testing%25123%26recipients%3D6010xxxxxxx%3B6012xxxxxxx%26referenceID%3Diyr340hbc6ja0b

Response

  • Single recipient - Successful
    {"status":"ok","msgCode":"E00001","statusMsg":"Completed successfully.","referenceID":["q5c502192aa869"],"balance":8901,"data":[{"recipients":"6010xxxxxxx","referenceID":"q5c502192aa869","charges":"1xx","currency":"Credit"}]}

  • Multiple recipients - Successful
    {"status":"ok","msgCode":"E00001","statusMsg":"Completed successfully.","referenceID":["q5c5021c306a95","q5c5021c306ae8"],"balance":8901,"data":[{"recipients":"6010xxxxxxx","referenceID":"q5c5021c306a95","charges":"1xx","currency":"Credit"},{"recipients":"6012xxxxxxx","referenceID":"q5c5021c306ae8","charges":"1xx","currency":"Credit"}]}

  • Unsuccessful
    {"status":"error","msgCode":"E00242","statusMsg":"invalid recipient(s).","invalidRecipients":["6010999999999"]}
*Response array encoded with JSON

Status Code List

Status Code Description
E00001 Completed successfully.
E00081 Account not active yet. Please contact our support.
E00242 Invalid recipient(s).
E00243 Please enter your message.
E00249 Maximum 10 SMS per recipient(s).
E00248 Please enter at least one recipient.
E00250 Insufficient balance.
E00253 Maximum 100 recipient(s).
E00359 Invalid API Key.
E00366 The message content contains international brand(s).
BE00035 The message not allow to send without company name.
BE00036 The message not allow to send without whitelisted.
BE00096 Duplicated reference id found.
BE00128 Completed successfully(low balance).

SMS123 Add Template through API

Post to SMS123


  • Post details are as below:
    URL: https://www.sms123.net/api/smsAddTemplate.php

  • Variable should be passed in with format below:
    Sample Data In
    {"apiKey ":"abc88888888acbde","email":"[email protected]","templateTitle":" AddTemplate02Jun2020","messageContent":"Hi, add template through api on 02 June 2020.","referenceId":"567890"}

    Param Data Type Description Sample
    apiKey Varchar API Key. (Find your API key at www.sms123.net My Account > Settings) abc88888888acbde
    email Varchar Email. (Find your API key at www.sms123.net My Account > Settings) [email protected]
    templateTitle Varchar Template title to be add AddTemplate02Jun2020
    messageContent Text Message content wanted to submit for whitelist Hi, add template through api on 02 June 2020.
    referenceId Varchar Reference ID to be return for you when status callback 567890

  • To be more secure, only POST method is accepted, GET method will not be accepted.

    ** apiKey, email, templateTitle and messageContent is necessary to pass in, but referenceId is not compulsary. If referenceId is passed from your site, we will return the same referenceId when callback for template status.
    ** Add template through API will be consider as submitted.

Return submitted template status to client site


  • Perform steps below to allow callback status after we approved or rejected your template:
    1. Pass your return URL to u
      [your website URL]/[your file path]
      For example: https://www.sms123.net/callback/receiveCallbackStatus.php
      https://www.sms123.net => [website URL]
      callback/receiveCallbackStatus.php => [file path]

    2. Tick the checkbox name as "Enable SMS Add Template Status Callback" at settings -> SMS Template Status Through API Callback section

  • Details below will be returned:
    Sample Data Return
    {"action":"templateStatusCallback","actionCode":"E00101","status":"Approved"," messageContent":"Hi, add template through api on 02 June 2020.","referenceId":"567890"}

    Param Data Type Description Sample
    action String Return command templateStatusCallback
    actionCode String Return Code E00101
    status String Template status Approved
    messageContent String Whitelisted message content Hi, add template through api on 02 June 2020.
    referenceId String Reference ID you passed to us when submit template 567890

    *Response array encoded with JSON

Status Code List

Status Code Description
E00101 Approved
E00102 Rejected
E00103 Others

GET method to get Account Balance

https://www.sms123.net/api/getBalance.php?apiKey=[APIKEY]&email=[EMAIL]

[APIKEY] API Key. (Find your API key at www.sms123.net My Account > Settings)
[EMAIL] Email. (Find your API key at www.sms123.net My Account > Settings)

Request and Response format


Request

https://www.sms123.net/api/getBalance.php?apiKey=[APIKEY]&email=[EMAIL]

Response

{"status":"[STATUS]","msgCode":"[MSGCODE]","statusMsg":"[ STATUSMSG]"," balance":"[ BALANCE]"}

*Response array encoded with JSON

Example code for request and response


Request

https://www.sms123.net/api/getBalance.php?apiKey=e0323drabst6728725da3dvdcra78910a&email=abcd1234@gmail.com

Response

{"status":"ok","msgCode":"E00001","statusMsg":"Completed successfully.","balance":"120.22"}

*Response array encoded with JSON

Status Code List

Status Code Description
E00001 Completed successfully.


GET method to get acount message history

Sample URL


- This URL will return today SMS sending history.

https:/www.sms123.net/api/getSentHistory.php?apiKey=680612580becfc76cd3468362bd045c&type=bulkSMS

- This URL will return history date from 1-10-2021 to 22-10-2021.

https://www.sms123.net/api/getSentHistory.php?apiKey=680612580becfbc76cd3468362bd045c&type=bulkSMS&fromDate=1-10-2021&toDate=22-10-2021

- This URL will return the history date from 1-10-2021 to 22-10-2021 of specific recipient number.

https://www.sms123.net/api/getSentHistory.php?apiKey=680612580becfbc76cd3468362bd045c&type=bulkSMS&fromDate=1-10-2021&toDate=22-10-2021&recipientNumber=60122261371

- This URL will return the history of a specific campaign.

https://www.sms123.net/api/getSentHistory.php?apiKey=680612580becfbc76cd3468362bd045c&type=bulkSMS&campaignName=20211022_test_url

- This URL will return the history date from 1-10-2021 to 22-10-2021 of a specific downline.

https://www.sms123.net/api/getSentHistory.php?apiKey=680612580becfbc76cd3468362bd045c&type=bulkSMS&fromDate=1-10-2021&toDate=22-10-2021&downLineEmail=testlak@hotmail.com

- This URL will return the first 100 history recorded from 1-10-2021 to 22-10-2021.

https://www.sms123.net/api/getSentHistory.php?apiKey=680612580becfbc76cd3468362bd045c&type=bulkSMS&fromDate=1-10-2021&toDate=22-10-2021&pageNumber=1

[APIKEY]

- API Key can be found under My account —> Manage API

[TYPE]

 - privateSMS (quick send)
- bulkSMS (bulk send)
- testSMS (test send)
[FROMDATE] - Value must be in (dd-mm-yyyy) format
- Will use today date if empty
[TODATE] - Value must be in (dd-mm-yyyy) format
- Will use today date if empty
[RECIPIENT_NUMBER] - Value must be in number
- For client who want to get history for specific recipient number
[CAMPAIGN_NAME] - For client who want to get history for specific campaign
[DOWN_LINE_EMAIL] - For client who want to get specific downline history 
[PAGENUMBER] - Will return 100 records if empty
- 1 for the first 100 records
- 2 for the next 100 records


Request and Response format


Request

https://sms123.net/api/getSentHistory.php?apiKey=[APIKEY]&type=[TYPE]&fromDate=[FROMDATE]&toDate[TODATE]&campaignName=[CAMPAIGNNAME]&recipientNumber=[RECIPIENTNUMBER]&downLineEmail=[DOWNLINEEMAIL]&pageNumber=[PAGENUMBER]

Response

{"status":[STATUS],"msgCode":[MSGCODE],"statusMsg":[STATUSMSG],"totalSMS":[TOTALSMS],"totalCharged":[TOTALCHARGED],"totalSent":[TOTALSENT],"sentHistory":[SENTHISTORY]}

*Response array encoded with JSON

Example code for request and response


Request

https://sms123.net/api/getSentHistory.php?apiKey=680612580becfbc76cd3468362bd045c&type=bulkSMS&fromDate=1-10-2021&toDate=22-10-2021&pageNumber=1

Response

{"status":"ok","msgCode":"E00001","statusMsg":"Completed successfully","totalSMS":3022,"totalCharged":"13,144.65","totalSent":3024,"sentHistory":[{"recipient":"85263592xxx”,”content":"test api 1","part":1,"total_cost":"16.67","scheduled_at":"22-Oct-21 04:47 PM"},{"recipient":"84968969xxx”,”content":"test api 1","part":1,"total_cost":"16.67","scheduled_at":"22-Oct-21 04:47 PM"}

*Response array encoded with JSON

Thing to expect for return

- Status

  • ok
  • error

- msgCode

  • E00001
  • E00002
  • E00003
  • E00359

- statusMsg

  • E00001 - Completed successfully or No record.
  • E00002 - You are not allowed to search more than one month or Invalid date range
  • E00003 - Type is empty
  • E00359 - Invalid API Key

- TotalSMS

- TotalCharged

  • Total cost

- TotalSent

- SentHistory

  • Recipient number
  • Content
  • Part
  • Total cost
  • Scheduled
  • Total click (If subscribed to Mtac)

Status Code List

Status Code Description
E00001 Completed successfully.
E00002 You are not allowed to search more than one month or Invalid date range.
E00003 Type is empty.
E00359 Invalid API Key.