Documentation

For developers who are looking to integrate SMSTech with an existing system, our comprehensive documentation provides all the information required to get you up and running.

SMS

send-sms

The Send-SMS call is the primary method of sending SMS.

Cost data is returned in the major unit of your account currency, e.g. dollars or pounds

NOTE: If you do not pass the ‘from’ parameter the messages will be sent from the shared number pool, unless you have a leased number on your account in which case it will be set as the Caller ID

When you set a alphanumeric for Caller ID, messages cannot be replied to

Parameter Description Required
message Message text YES
to Number or set of up to 10,000 numbers to send the SMS to. If your number set has some invalid numbers, they won’t cause validation error, but will be returned as ‘fails’ parameter of the response (see example 3).
Number must be defined in international format.
Some examples by destination:
AU 61491570156,
NZ 64212670129,
SG 6598654321,
UK 44750017696,
US 1213811413
If list_id is not set
from Set the alphanumeric Caller ID, mobile numbers should be in international format. Maximum 11 characters. No spaces. If not set will use shared number pool. NO
send_at A time in the future to send the message
Note: All returned timestamps are in ISO8601 format e.g. YYYY-MM-DD HH:MM:SS. The zone is always UTC.
NO
list_id This ID is the numerical reference to one of your recipient lists
Note: List ID’s are made up of digits and will be returned by the add-list call, or can be found at any time by logging into your account and visiting your contacts page.
If to is not set
dlr_callback A URL on your system which we can call to notify you of Delivery Receipts. If required, this Parameter can be different for each message sent and will take precedence over the DLR Callback URL supplied by you in the API Settings. NO
reply_callback A URL on your system which we can call to notify you of incoming messages. If required, this parameter can be different and will take precedence over the Reply Callback URL supplied by you on the API Settings. NO
validity Specify the maximum time to attempt to deliver. In minutes, 0 (zero) implies no limit. NO
replies_to_email Specify an email address to send responses to this message.
NOTE: specified email must be authorised to send messages via add-email or in your account under the ‘Email SMS’ section.
NO
from_shared Forces sending via the shared number when you have virtual numbers NO
countrycode Formats numbers given to international format for this 2 letter country code. i.e. 0422222222 will become 6142222222 when countrycode is AU. Codes available AU Australia, NZ New Zealand SG Singapore GB United Kingdom US United States NO

Example

Send an SMS message to one or many recipients from your own database

curl https://api.transmitsms.com/send-sms.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d 'message=Hi guys' \
-d to=61491570156,61491570157,61491570158

JSON Response XML Response
{
message_id: 19835,
recipients: 3,
cost: 1.000
}
<?xmlversion="1.0"encoding="UTF-8"?> <response> <message_id>19835</message_id> <recipients>3</recipients> <cost>1.000</cost> </response>

Example

send an SMS message to a recipient list

curl https://api.transmitsms.com/send-sms.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d 'message=Hello loyal followers' \
-d list_id=12345

JSON Response XML Response
{
message_id: 12345,
send_at: "2013-06-01 12:34:00",
recipients: 12,
cost: 1.000,
list: {
id: 12345,
name: "BFFs"
}
}
<?xmlversion="1.0"encoding="UTF-8"?> <response> <message_id>12345</message_id> <send_at>2013-06-01 12:34:00</send_at> <recipients>12</recipients> <cost>1.000</cost> <list> <id>12345</id> <name>BFFs</name> </list> </response>

Example

send an SMS message set of numbers, some of which are invalid

curl https://api.transmitsms.com/send-sms.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d 'message=Hi guys' \
-d to=61491570156,61491570157,00000000001,alphanumber

JSON Response XML Response
{
message_id: 19835,
recipients: 2,
cost: 1.000,
fails: {
0: 00000000001,
1: alphanumber
}
}
<?xmlversion="1.0"encoding="UTF-8"?> <response> <message_id>19835</message_id> <recipients>2</recipients> <cost>1.000</cost> <fails>00000000001</fails> <fails>alphanumber</fails> </response>
ERROR Code Header Description
LEDGER_ERROR 400 There was a problem with payment. Please check the output for more details.
LIST_EMPTY 400 The list you provided doesn’t have active recipients.
RECIPIENTS_ERROR 400 No valid recipients left after validation.

PHP Examples

<?php include'../../APIClient2.php'; $api=new transmitsmsAPI("API_KEY",'API_SECRET'); // sending to a set of numbers $result=$api->sendSms('test','6140000000, 6140000001','callerid'); // sending to a list //$result=$api->sendSms('test', null, 'callerid', null, 6151); if($result->error->code=='SUCCESS') { echo"Message to {$result->recipients} recipients sent with ID {$result->message_id}, cost {$result->cost}"; } else { echo"Error: {$result->error->description}"; }

format-number

Format and validate a given number.

PARAMETER DESCRIPTION REQUIRED
msisdn The number to check YES
countrycode 2 Letter countrycode to validate number against YES

countrycode values: AU = Australia, SG = Singapore, GB = United Kingdom, NZ = New Zealand, US = United States

Example

curl https://api.transmitsms.com/format-number.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d 'msisdn=0455667889' \
-d 'countrycode=AU'

JSON RESPONSE

{
"error": {
"code": "SUCCESS",
"description": "OK"
},
"number": {
"countrycode": 61,
"international": 61455667889,
"isValid": true,
"national_leading_zeroes": 455667889,
"nationalnumber": 455667889,
"rawinput": null,
"type": 1
}
}

XML RESPONSE

<?xml version="1.0" encoding="UTF-8"?> <response> <number> <countrycode>61</countrycode> <nationalnumber>455667889</nationalnumber> <national_leading_zeroes>0455667889</national_leading_zeroes> <rawinput /> <international>+61455667889</international> <type>1</type> <isValid>true</isValid> </number> <error> <code>SUCCESS</code> <description>OK</description> </error> </response>

PHP Example

formatNumber('0455667889', 'AU');
if($result->error->code=='SUCCESS')
{
echo"Number valid and in international: {$result->number->international}";
}
else
{
echo"Error: {$result->error->description}";
}

get-sms

Get information about a message you have sent.

PARAMETER DESCRIPTION REQUIRED
message_id Message ID YES

Example

curl https://api.transmitsms.com/get-sms.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d message_id=48782

JSON RESPONSE

{
message_id: 48782,
send_at: "2013-06-01 12:34:00",
recipients: 12,
cost: 1.000,
list: {
id: 123,
name: "BFFs"
}
}

XML RESPONSE

<?xmlversion="1.0"encoding="UTF-8"?> <response> <message_id>48782</message_id> <send_at>2013-06-01 12:34:00</send_at> <recipients>12</recipients> <cost>1.000</cost> <list> <id>123</id> <name>BFFs</name> </list> </response>

PHP Example

<?php include'../../APIClient2.php'; $api=new transmitsmsAPI("API_KEY",'API_SECRET'); $result=$api->getSms(49680); if($result->error->code=='SUCCESS') { echo"Message to {$result->recipients} recipients sent with ID {$result->message_id}, cost {$result->cost}"; } else { echo"Error: {$result->error->description}"; }

get-sms-stats

Get information about a message you have sent.

PARAMETER DESCRIPTION REQUIRED
message_id Message ID YES

Example

curl https://api.transmitsms.com/get-sms-stats.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d message_id=48782

JSON RESPONSE

stats: {
total: 4,
recipientCount: 4,
delivered: 4,
pending: 0,
bounced: 0,
responses: 0,
opt-outs: 0,
link_hits: 0
}

XML RESPONSE

<?xmlversion="1.0"encoding="UTF-8"?> <response> <stats> <total>4</total> <recipientCount>4</recipientCount> <pending>0</pending> <bounced>0</bounced> <responses>0</responses> <opt-outs>0</opt-outs> <link_hits>0</link_hits> </stats> </response>

PHP Example

<?php include'../../APIClient2.php'; $api=new transmitsmsAPI("API_KEY",'API_SECRET'); $result=$api->getSmsStats(49680); if($result->error->code=='SUCCESS') { print_r($result->stats); } else { echo"Error: {$result->error->description}"; }

get-sms

Get information about a message you have sent.

PARAMETER DESCRIPTION REQUIRED
message_id Message ID YES

Example

curl https://api.transmitsms.com/get-sms.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d message_id=48782

JSON RESPONSE

{
message_id: 48782,
send_at: "2013-06-01 12:34:00",
recipients: 12,
cost: 1.000,
list: {
id: 123,
name: "BFFs"
}
}

XML RESPONSE

<?xmlversion="1.0"encoding="UTF-8"?> <response> <message_id>48782</message_id> <send_at>2013-06-01 12:34:00</send_at> <recipients>12</recipients> <cost>1.000</cost> <list> <id>123</id> <name>BFFs</name> </list> </response>

PHP Example

<?php include'../../APIClient2.php'; $api=new transmitsmsAPI("API_KEY",'API_SECRET'); $result=$api->getSms(49680); if($result->error->code=='SUCCESS') { echo"Message to {$result->recipients} recipients sent with ID {$result->message_id}, cost {$result->cost}"; } else { echo"Error: {$result->error->description}"; }

get-user-sms-responses

Pick up responses to messages you have sent. Instead of setting message ID, you should provide a time frame.

PARAMETER DESCRIPTION REQUIRED
start A timestamp to start the report from NO
end A timestamp to end the report at NO
page Page number, for pagination NO
max Maximum results returned per page NO
keywords Filter if keyword responses should be included. Can be:
‘only’ – only keyword responses will be included‘omit’ – only regular campaign responses will be included
‘both’ – both keyword and campaign responses will be included (default)
NO
include_original include text of original message NO

Example

get SMS responses for the previous day

curl https://api.transmitsms.com/get-user-sms-responses.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d start=”2013-01-01 00:00:00”
-d end=”2013-01-02 00:00:00”

JSON RESPONSE

{
page: {
count: 3,
number: 1
},
total: 5003,
responses: [
{
id: 12345,
list_id: 567,
message_id: 4565,
received_at: "2013-06-21 23:45:11",
first_name: "Charles",
last_name: "Gordon",
msisdn: "61491570156",
response: "23 Inspiring St, Fairlight"
}
]
}

XML RESPONSE

<?xmlversion="1.0"encoding="UTF-8"?> <response> <page> <count>3</count> <number>1</number> </page> <total>5003</total> <responses> <id>12345</id> <list_id>567</list_id> <message_id>4565</message_id> <received_at>2013-06-21 23:45:11</received_at> <first_name>Charles</first_name> <last_name>Gordon</last_name> <msisdn>61491570156</msisdn> <response>23 Inspiring St, Fairlight</response> </responses> </response>

get-sms-sent

Get a list of recipients from a message send. Get up to date information such as opt-out status and delivery status.

PARAMETER DESCRIPTION REQUIRED
message_id Message ID’s are made up of digits YES
optouts Whether to include optouts. Valid options are:
only – only get optouts
omit – do not get optouts
include – get all recipients including optouts (default)
NO
page Page number, for pagination NO
max Maximum results returned per page NO
keywords Filter if keyword responses should be included. Can be:
‘only’ – only keyword responses will be included‘omit’ – only regular campaign responses will be included
‘both’ – both keyword and campaign responses will be included (default)
NO
delivery Only show messages with requested delivery status. Valid options are:
delivered – only show delivered messages
failed – only show failed messages
pending – only show pending messages
NO

Example

get all message recipients

curl https://api.transmitsms.com/get-sms-sent.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d message_id=48782

Example

get all recipients who’ve opted out

curl https://api.transmitsms.com/get-sms-sent.json \
-u 2e24c1cbdd987221e165d543f34b84bf:secret \
-d message_id=48782 \
-d optouts=only

JSON RESPONSE

{
page: {
count: 1,
number: 1
},
total: 2,
message: {
message_id: 565645,
send_at: "2013-06-01 12:34:00",
recipients: 2,
list: {
id: 123,
name: "BFFs"
}
},
recipients: [
{
first_name: "Charles",
last_name: "Gordon",
msisdn: "61491570156",
optout: false,
delivery_status: "delivered"
},
{
first_name: "Alex",
last_name: "Fergle",
msisdn: "61491570157",
optout: true,
delivery_status: "soft-bounce"
}
]
}

XML RESPONSE

<?xmlversion="1.0"encoding="UTF-8"?> <response> <page> <count>1</count> <number>1</number> </page> <total>2</total> <message> <message_id>565645</message_id> <send_at>2013-06-01 12:34:00</send_at> <recipients>2</recipients> <list> <id>123</id> <name>BFFs</name> </list> </message> <recipients> <first_name>Charles</first_name> <last_name>Gordon</last_name> <msisdn> 61491570156 </msisdn> <optout>false</optout> <delivery_status>delivered</delivery_status> </recipients> <recipients> <first_name>Alex</first_name> <last_name>Fergle</last_name> <msisdn>61491570157</msisdn> <optout>true</optout> <delivery_status>soft-bounce</delivery_status> </recipients> </response>

DELIVERY STATUS DESCRIPTION
delivered Message delivered to handset
pending No confirmation yet
soft-bounce Handset out of range or switched off
hard-bounce Number disconnected

PHP Example

<?php include '../../APIClient2.php'; $api=new transmitsmsAPI("API_KEY",'API_SECRET'); $offset=0; $limit=10; $result=$api->getSmsSent(49606, $offset, $limit); if($result->error->code=='SUCCESS') { echo "Message sent to {$result->total} recipients, showing page {$result->page->number} of {$result->page->count} <hr>"; foreach ($result->recipients as $recipient) { echo "{$recipient->first_name} {$recipient->last_name} - {$recipient->delivery_status} <br>"; } } else { echo "Error: {$result->error->description}"; }