API Documentation
Back to top  

TMRestClient

API client to access Text Marketer's RESTful API, allows you to send SMS, check credits, create accounts, and more.

This class has been designed to be sub-classed, so that you can create a subclass with your API username/password pre-set in the variables $defaultUsername and $defaultPassword and thus use new versions of this class as they are released, without the need for modifying your defaults.

CHANGE LOG

v1.4 Added delete scheduled SMS v1.3 Added schedule parameter to SMS send. v1.2 Misc refactoring and bug fixes. Improved suitability for subclassing. Added sub-account creation function. Updated to REST DTDs v1.6.

copyright

Copyright (c) 2012, Text Marketer
link

http://www.textmarketer.co.uk/developers/restful-api.htm
version

Methods

Constructor for the TMRestClient class

__construct(string $username = null, string $password = null, string $env = 'sandbox') : \TMRestClient

Arguments

$username

string

your API Gateway Username

$password

string

your API Gateway Password

$env

string

possible values 'sandbox' or 'production'

Response

\TMRestClient

TMRestClient

Make a call to TM Rest API Gateway to test if the username and password are correct

isLoginValid() : boolean

isLoginValid()) echo 'Login is valid.'; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

throws

on error

Response

boolean

TRUE if login valid, FALSE if username or password not correct

Send a text message to the specified recipient.

sendSMS(string $message, string $mobile_number, string $originator, integer $validity = 72, string $email = '', string $custom = '', string $schedule = null) : array
link

http://www.textmarketer.co.uk/blog/2009/07/bulk-sms/supported-and-unsupported-characters-in-text-messages-gsm-character-set/
throws

on error sendSMS('Hello SMS World!', '447777123123', 'Hello World'); echo "Used {$result['credits_used']} Credits, message ID {$result['message_id']}, Scheduled ID {$result['scheduled_id']}"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$message

string

The textual content of the message to be sent. Up to 612 characters from the GSM alphabet. The SMS characters we can support is documented at @link http://www.textmarketer.co.uk/blog/2009/07/bulk-sms/supported-and-unsupported-characters-in-text-messages-gsm-character-set/. Please ensure that data is encoded in UTF-8.

$mobile_number

string

The mobile number of the intended recipient, in international format, e.g. 447777123123. Only one number is allowed. To send a message to multiple recipients, you must call the API for each number.

$originator

string

A string (up to 11 alpha-numeric characters) or the international mobile number (up to 16 digits) of the sender, to be displayed to the recipient, e.g. 447777123123 for a UK number.

$validity

integer

Optional. An integer from 1 to 72, indicating the number of hours during which the message is valid for delivery. Messages which cannot be delivered within the specified time will fail.

$email

string

Optional. Available to txtUs Plus customers only. Specifies the email address for incoming responses. If you specify an email address, you must specify an originator that is a txtUs Plus number that is on your account, or you will get an error response.

$custom

string

Optional. An alpha-numeric string, 1-20 characters long, which will be used to 'tag' your outgoing message and will appear in delivery reports, thus facilitating filtering of reports

$schedule

string

Optional parameter to schedule the message to send at a given time, should be in ISO 8601 format or UNIX Timestamp (Europe/London time)

Response

array

array with 4 keys: 'message_id', 'scheduled_id', 'credits_used', 'status' e.g. $result['message_id']

Delete a scheduled text message.

deleteSMS(string $scheduled_id) : array
throws

on error deleteSMS('101'); echo "Scheduled ID {$result['scheduled_id']}, Status: {$result['status']}"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$scheduled_id

string

The id of the scheduled text message, as returned by the sendSMS method.

Response

array

array with 2 keys: 'scheduled_id', 'status', e.g. $result['status']

Get the number of credits currently available on your account.

getCredits() : int
throws

on error getCredits().'credits.'; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Response

int

number of credits currently available on your account.

Transfer credits from one account to another account, using the account number for the target.

transferCreditsToAccount(integer $quantity, string $targetAccountNumber) : array
throws

on error transferCreditsToAccount(3, '1234'); echo "Transfered 3 Credits (have {$result['source_credits_after']} now), to account 1234, now with {$result['target_credits_after']} Credits"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$quantity

integer

The number of credits to transfer from the source account to the target account.

$targetAccountNumber

string

The account number of the account to transfer the credits to (available in the web-based UI)

Response

array

array with four keys: 'source_credits_before', 'source_credits_after', 'target_credits_before' and 'target_credits_after' e.g. $result['source_credits_after']

Transfer credits from one account to another account, using the username for the target.

transferCreditsToUser(integer $quantity, string $target_username, string $target_password) : array
throws

on error transferCreditsToUser(3, 'targetusername', 'targetpassword'); echo "Transfered 3 Credits (have {$result['source_credits_after']} now), to targetusername, now with {$result['target_credits_after']} Credits"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$quantity

integer

The number of credits to transfer from the source account to the target account.

$target_username

string

The username of the account to transfer the credits to.

$target_password

string

The password of the account to transfer the credits to.

Response

array

array with four keys: 'source_credits_before', 'source_credits_after', 'target_credits_before' and 'target_credits_after' e.g. $result['source_credits_after']

DEPRECATED

getKeyword($keyword)
deprecated

Replaced by TMRestClient=>getKeywordAvailability()

Arguments

$keyword

Get the availability of a given reply keyword.

getKeywordAvailability(string $keyword) : array

A reply keyword allows you receive incoming text messages to your account by providing people with a keyword, which they text to the short code 88802, e.g. text 'INFO' to 88802 to see this in action.

throws

on error getKeyword('gold'); echo "The 'gold' keyword is available ({$result['available']}), recycled ({$result['recycle']})"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$keyword

string

the keyword to check is availability

Response

array

array with two keys: 'available' and 'recycle' e.g. $result['available']

Get a list of available 'send groups' - pre-defined groups containing a list of mobile numbers to send a message to.

getGroups() : array

Also lists 'stop groups' - numbers in these groups will never be sent messages. Every account has at least one stop group, so that your recipients can always opt out of receiving messages from you. This is a legal requirement.

throws

on error getGroups(); foreach($groups as $group) foreach($group as $key => $value) echo "$key => $value
"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Response

array

array with all groups, one per array row, each group row have 4 keys: 'is_stop', 'id', 'numbers' and 'name' e.g. name of the first returned group $groups[0]['name']

Add a number/numbers to a 'send group' (excluding 'merge' groups).

addNumbersToGroupWithName(array $numbersArray, string $groupName) : array
throws

on error addNumbersToGroup('My Group', array('447777000001','447777000002','447777000003')); echo 'Numbers added: '.count($result['added']).'
.; foreach ($result['added'] as $number) echo "$number
"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$numbersArray

array

The MSISDN (mobile number(s)) you wish to add

$groupName

string

Group name or group ID to add the numbers to

Response

array

array with 3 keys: 'added', 'stopped' and 'duplicates', each one with an array of numbers

DEPRECATED - use addNumbersToGroupWithName() instead

addNumbersToGroup($groupName, $numbers)
deprecated

Replaced by TMRestClient->addNumbersArrayToGroup()

Arguments

$groupName

$numbers

Shows the details of a group.

getGroup(string $group) : array

Shows only one group, and includes all the numbers in the group, if there are any.

throws

on error getGroup('My Group'); echo "Numbers in group: {$result['numbers']}
"; foreach ($result['number'] as $number) echo "$number
"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$group

string

Group name or group ID to get the details of

Response

array

array with 5 keys: 'name', 'numbers', 'id', 'is_stop' and 'number'

Create a new group.

addGroup(string $group) : array
throws

on error addGroup('New Group'); echo "The ID of {$result['name']} is {$result['id']}"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$group

string

the new group name

Response

array

array with 4 keys: 'name', 'numbers', 'id', 'is_stop'

Retrieve a list of available delivery report names.

getDeliveryReports() : array
throws

on error getDeliveryReports(); echo "User Directory: {$result['userdirectory']}
"; foreach($result['reports'] as $key => $report) echo "Report number $key: Name->{$report['name']}, Last Updated->{$report['last_updated']}, Extension->{$report['extension']}
"; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Response

array

array with 2 keys: 'userdirectory' and 'reports'; reports is an array where each row is a report array with keys 'name', 'last_updated', 'extension'

Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign.

getDeliveryReport(string $name, string $date_start = null, string $date_end = null, string $custom = null) : array

Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns. NOTE that an exception is thrown if no reports are found

e.g. for a delivery report with the name 'mycampaign-020411' $result = $tmClient->getDeliveryReport('mycampaign-020411');

e.g. to get the delivery report details for 'mycampaign-020411' between 01:00 and 02:00 on 1st Jan 2011 $result = $tmClient->getDeliveryReport('mycampaign-020411', '2011-01-01T01:00:00+00:00', '2011-01-01T02:00:00+00:00'); $result = $tmClient->getDeliveryReport('mycampaign-020411', '2011-01-01T01:00:00+00:00', time());

e.g. to get delivery report details for all campaigns and API sends between the same dates as above $result = $tmClient->getDeliveryReport('all', '2011-01-01T01:00:00+00:00', '2011-01-01T02:00:00+00:00'); $result = $tmClient->getDeliveryReport('all', '2011-01-01T01:00:00+00:00', time());

e.g. for a delivery report with the name 'mycampaign-020411' and custom tag 'test' or all $result = $tmClient->getDeliveryReport('mycampaign-020411', null, null, 'test'); $result = $tmClient->getDeliveryReport('all', null, null, 'test');

  • e.g. same as previous but between 2 dates $result = $tmClient->getDeliveryReport('mycampaign-020411', '2011-01-01T01:00:00+00:00', '2011-01-01T02:00:00+00:00', 'test'); $result = $tmClient->getDeliveryReport('all', '2011-01-01T01:00:00+00:00', time(), 'test');
throws

on error OR NO REPORTS FOUND (404) getDeliveryReport('all'); foreach ($result as $key => $report) { echo "Report number $key: Name->{$report['name']}, Last Updated->{$report['last_updated']}, Extension->{$report['extension']}
"; foreach ($report['reportrow'] as $key => $reportrow) { echo "Message ID: {$reportrow['message_id']}, number: {$reportrow['mobile_number']}, Status:{$reportrow['status']}, Updated: {$reportrow['last_updated']}
"; } } } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Arguments

$name

string

Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data

$date_start

string

Optional parameter get delivery report from $date_start, should be in ISO 8601 or UNIX Timestamp (Europe/London time)

$date_end

string

Optional parameter get delivery report to $date_end, should be in ISO 8601 or UNIX Timestamp (Europe/London time)

$custom

string

Optional Can specify a custom 'tag', which will restrict the search to those messages you sent with that tag (see 'custom' parameter of sendSms method).

Response

array

array with 4 keys: 'name', 'last_updated', 'extension' and 'reportrow', reportrow is an array with keys 'message_id', 'mobile_number', 'status' and 'last_updated'

Create a new account (requires additional permissions on your account, please contact Text Marketer to apply)

createSubAccount(string $companyName, \type $notificationMobile = null, \type $notificationEmail = null, string $username = null, string $password = null, string $promoCode = null, boolean $overrideRates = false) : array

createAccount('New Company'); } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

throws

on error

Arguments

$companyName

string

the company name for the new account owner

$notificationMobile

\type

(optional) the mobile number of the account (required if $notificationEmail is not set)

$notificationEmail

\type

(optional) the email address of the account (required if $notificationMobile is not set)

$username

string

(optional) the username you wish to set on the new account - the API username will be the same

$password

string

(optional) the password you wish to set on the new account - the API password will be the same

$promoCode

string

(optional) a promotional code entitling the account to extra credits

$overrideRates

boolean

If set to true, use the credits rates set on your main account (the account used to access the API), rather than the Text Marketer defaults.

Response

array

array with 10 keys: 'api_password', 'api_username', 'company_name', 'create_date', 'credits', 'password' and 'username', 'notification_email', 'notification_mobile', 'account_id'

Get the all errors encountered after the last call to the API

getLastErrors() : array

Response

array

associative array with 'error_code'=>'error message' format. Could have more then 1 error code. isLoginValid()) echo 'Login is valid.'; } catch (Exception $ex) { $errors = $tmClient->getLastErrors(); foreach($errors as $errorcode => $errormsg) echo "Code $errorcode: $errormsg"; } ?>

Add one error to $lastErrors, use getLastErrors() to retrieve them

addError(string $code, string $msg, boolean $new = true)

Arguments

$code

string

Error code

$msg

string

Error message

$new

boolean

TRUE is a new error, code

Make the HTTP call to the REST API

restGatewayCall($service = 'credits', $method = 'GET', $params = NULL) : string
throws

on error

Arguments

$service

$method

$params

Response

string

$xml XML response from the REST API

Internal function

doCreateAccount(string $companyName, \type $notificationMobile = null, \type $notificationEmail = null, string $username = null, string $password = null, string $promoCode = null, boolean $overrideRates = false, $resource = 'account/sub') : array
throws

on error

Arguments

$companyName

string

$notificationMobile

\type

$notificationEmail

\type

$username

string

$password

string

$promoCode

string

$overrideRates

boolean

$resource

Response

array

Properties

PROD_URL

PROD_URL
static

SAND_URL

SAND_URL
static

The client class version - internal use only, DO NOT change this

VERSION
static
var

Default API username - you can set this if you want, but it is strongly recommended to pass it in to the constructor instead.

defaultUsername
var

Default API password - you can set this if you want, but it is strongly recommended to pass it in to the constructor instead.

defaultPassword
var

username

username

password

password

lastErrors

lastErrors

apiUrl

apiUrl

responseBody

responseBody

forceSandbox

forceSandbox