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


We created a new viewing experience for our SMS API documentation. It's now all in one central location. Click here to check it out!

You can elect to pass us the recipient numbers from your database each time you make a call, or you can elect to store recipient data in a contact list and submit only the list_id to trigger the send. This is best for large databases. To add a list please refer to the add-list call.


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

messageMessage textYES
toNumber 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
fromSet 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_atA 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_idThis 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_callbackA 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_callbackA 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
validitySpecify the maximum time to attempt to deliver. In minutes, 0 (zero) implies no limit.NO
replies_to_emailSpecify 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_sharedForces sending via the shared number when you have virtual numbersNO 
countrycodeFormats 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 StatesNO
tracked_link_url Converts this URL to unique tapth.is/xxxxxx tracking link for each contact. Inserted into message with variable [tracked-link]. Clicks on this URL will be passed as notifications via 'Link hits callback URL' defined in account settings. 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

{
  message_id: 19835,
  recipients: 3,
  cost: 1.000
}

XML Response

<?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

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

XML Response

<?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

{
  message_id: 19835,
  recipients: 2,
  cost: 1.000,
  fails: {
    0: 00000000001,
    1: alphanumber
  }
}

XML Response

<?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_ERROR400There was a problem with payment. Please check the output for more details.
LIST_EMPTY400The list you provided doesn't have active recipients.
RECIPIENTS_ERROR400No 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}";
 }