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!

This method adds multiple recipients to a contact list. Please read the 'contact-lists.add-recipient' documentation as this is a convenience method to replicate adding single recipients in a batch. Possible results include:



ADDED - recipient was added succesfully.
DUPLCIATE / UPDATED - recipient already existed and the recipients data was updated.
OPTOUT - recipient existed on list and has unsubscribed at some point so cannot be added / updated.
DUPLICATE_DELETED - recipient already existed but has been deleted at some point.


Parameters


  • list_id - list identifier required in one of the two following formats:
    • integer - the list id as a numeric value, this can be found by requesting 'contact-lists.get' and using corresponding id values from the dataset
      OR
    • string - the list name EXACTLY as it is in the 'contact-lists.get' response.
  • recipients - array of recipients to add, each with the following:
    • mobile - string - recipients mobile number, required in one of the two following formats:
      • as a local number (you will need to pass a valid iso2 code in the mobileCountry parameter)
      • as an internationally formatted number (e.g. international code + mobile)
    • mobileCountry - string - iso2 code identifying the recipients country (e.g. AU) - only required when a local number is passed in the mobile field.
    • firstname - string - recipients firstname
    • lastname - string - recipients lastname
    • custom1 - string
    • custom2 - string
    • custom3 - string
    • custom4 - string
    • custom5 - string
    • custom6 - string
    • custom7 - string
    • custom8 - string
    • custom9 - string
    • custom10 - string


 




 




XML Request Example


<?xml version='1.0'?>

<request>

	<interface>PHP</interface>

	<version>0.3</version>

	<key>API_KEY</key>

	<secret>API_SECRET</secret>

	<method>contact-lists.add-multiple-recipients</method>

	<params>

		<list_id>1076</list_id>

		<recipients>

			<recipient>

				<mobile>614xxxxxxxx</mobile>

				<mobile_dest_country />

				<firstname>Jane</firstname>

				<lastname>Doe</lastname>

				<custom1>whatever</custom1>

			</recipient>

			<recipient>

				<mobile>614xxxxxxxx</mobile>

				<mobile_dest_country>AU</mobile_dest_country>

				<firstname>John</firstname>

				<lastname>Doe</lastname>

			</recipient>

		</recipients>

	</params>

</request>







XML Response Example


<?xml version='1.0'?>

<xml>

	<method>contact-lists.add-multiple-recipients</method>

	<total>1</total>

	<time>2009-12-21 23:08:21 GMT</time>

	<timestamp>1261436901 GMT</timestamp>

	<data>

		<list_id>1076</list_id>

		<total_added>0</total_added>

		<total_recipients>4</total_recipients>

		<results>

			<recipient>

				<mobile>61416377778</mobile>

				<mobile_as_passed>614xxxxxxxx</mobile_as_passed>

				<mobile_country_as_passed></mobile_country_as_passed>

				<result>DUPLCIATE / UPDATED</result>

			</recipient>

			<recipient>

				<mobile>61416377777</mobile>

				<mobile_as_passed>614xxxxxxxx</mobile_as_passed>

				<mobile_country_as_passed>AU</mobile_country_as_passed>

				<result>ADDED</result>

			</recipient>

		</results>

	</data>

</xml>







PHP Example


Download the PHP API Client


<?php



// change api key and secret to your own

$myAPIKey = "API_KEY";

$myAPISecret = "API_SECRET";



// include base class

require('APIclient.php');



// create new client object

$transmitsmsAPI = new transmitsmsAPI($myAPIKey, $myAPISecret);



// set parameters

$list_id = 1076;

$recipients = array(

	array("mobile" => '6141xxxxxxx', 'mobile_dest_country' => '', 'firstname' => 'Jane', 'lastname' => 'Doe', 'custom1' => 'whatever'),

	array("mobile" => '041xxxxxxx', 'mobile_dest_country' => 'AU', 'firstname' => 'John', 'lastname' => 'Doe'),

);



// execute request

$methodResponse = $transmitsmsAPI->addContactListRecipientsMulti($list_id, $recipients);



// parse response into xml object

$xml = @simplexml_load_string($methodResponse);



echo 'The list now has ' . $xml->total . ' recipients<hr />';

foreach ($xml->data->results->recipient as $recipient) {

	echo (string) $recipient->mobile . ' was ' . (string) $recipient->result . '<br />';

}



?>






GET Example


These method does not support URL based requests.