This API is designed to be an ultra simple HTTP integration specifically for SMS.
This endpoint is simplified and supports sending SMS only.
For access to our fully featured tool-kit, please refer to our REST API.
Head to https://bestsms.au/signup to create a new account.
A test account is possible, however creating a commercial account and using the Mode=Test function of the API is simpler to use when you’re ready to push your application live.
After completing the sign up form, a sales consultant will manually activate your account. This may take one business day. Once the account has been activated, you will be able to Create a new API user token.
Using the API will require a Sender and Token pair to authenticate with the API.
You can generate this using the Web Dashboard under: Users | Outbound Users | Create | API Options
Sender = Sender
API Key = Token
When submitting a message via HTTP, the server will respond:
200 OK, OK Thanks
400 BAD REQUEST, %ERROR REASON%
500 Internal Server Error
Resources:
[email protected]
Token=ta8wr7ymd
Number=0421000001
Message=Hello, this is a test message from Department01. Thank you.
Sample response:
By default API will respond in JSON format with the message id
{
"Result": "Success",
"MessageID": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"
}
| Parameter | Example Value | Description | |
|---|---|---|---|
| Sender | [email protected] | Sender value set up in Create a new API user token | |
| Token | ta8wr7ymd | Token value set up in Create a new API user token | |
| Number | 0421000001 | Destination mobile number in dialling format (02, 0064, +64). We recommend implementing a prefix check to limit potential Toll Fraud |
|
| Message | Hello, this is a test message from Department01. Thank you. | Plain or UTF-8 formatted SMS message | |
| Parameter | Example Value | Description | |
|---|---|---|---|
| MessageID | ID123456 | A message tracking identifier (maximum 40 characters, alphanumeric) | |
| SMSEmailReply | [email protected] | For email (SMTP) reply receipt notifications | |
To resend or retry sending a message via the REST API, this will need to be submitted as a new, unique message.
To resend or retry sending a message via the Web Dashboard, once logged in and viewing an individual message, you will see Resubmit and Forward buttons.
Delivery Reports advise whether delivery was successful. If not, it will describe why.
Each delivery report type is optional and multiple delivery report types can be used.
You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.
Delivery reports are emailed as an HTML email for viewing by an end-user. Your sales representative can enable this for you.
Whitelabelling of SMTP Email reports is available.
The email address to receive SMS Reply reports can be specified on the original message submission using the SMSEmailReply parameter.
To receive Delivery Reports via Webhook, please advise the URL to submit to.
Webhooks are provided as an HTTP POST in either XML or JSON format (your preference).
Supplied parameters are:
| Parameter | Example Value | Description |
|---|---|---|
| Sender | [email protected] | Webhook sender authentication (can configure a unique Sender if required) |
| Token | ta8wr7ymd | Webhook token authentication (can configure a unique Token if required) |
| Type | SMS | To send SMS Message |
| Destination | +61421000001 | Destination that the webhook is for (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format) |
| MessageID | js82hn8n | MessageID parameter supplied when sending your original API call |
| JobNumber | 10C7B9A0 | Eight digit alphanumeric tracking number (our internal Job Number) |
| SentTime | 16/10/2023 13:43 p.m. | Time message was completed (Sender's local time time in 'dd/MM/yyyy HH:mm tt' format) |
| Status | SUCCESS | For submission results, values are SUCCESS, FAILED, PENDING For reply reports, this will be RECEIVED For additional analytics, this will be UPDATED |
| Result | delivered | Final delivery result and/or the cause for a message delivery failure For reply reports, this will be RECEIVED For additional analytics, this will be the event description |
| Message | This is a reply. | This field will only contain data if 'Type=SMSReply' |
| Price | 0.20 | Your cost for this transaction, charged by us to you |
| Detail | SMSParts:2 | Additional billing detail: "SMSParts" |
API users are able to poll for the status of a message via the GET Status API, as well as capture any SMS replies received.
The GET Poll options are described in the REST API guide:
| API Name | Description |
| GET Status Poll | Poll for the delivery status of an outbound message (tracked using the MessageID) |
| GET Inbound SMS Poll | Poll for a list of all SMS received in a given time-frame |
| GET SMS Reply Poll | Poll for replies to a specific outbound SMS message (tracked using the MessageID) |