« Back to Documentation Overview

listBatchSubscribe – v1.1

 listBatchSubscribe(string apikey, string id, array batch, boolean double_optin, boolean update_existing, boolean replace_interests)

Subscribe a batch of email addresses to a list at once

Section
List Related
Parameters
apikey a valid API Key for your user account. Get by calling Get by visiting your API dashboard
id the list id to connect to. Get by calling lists()
batch an array of structs for each address to import with two special keys: "EMAIL" for the email address, and "EMAIL_TYPE" for the email type option (html or text)
double_optin flag to control whether to send an opt-in confirmation email - defaults to true
update_existing flag to control whether to update members that are already subscribed to the list or to return an error, defaults to false (return error)
replace_interests flag to determine whether we replace the interest groups with the updated groups provided, or we add the provided groups to the member's interest groups (optional, defaults to true)
Returns
struct Array of result counts and any errors that occurred
Returned Fields
integersuccess_countNumber of email addresses that were succesfully added/updated
integererror_countNumber of email addresses that failed during addition/updating
arrayerrorsArray of error structs. Each error struct will contain "code", "message", and the full struct that failed

Examples (2)

download example code

[1] mcapi_listBatchSubscribe.php

  1. <?php
  2. /**
  3. This Example shows how to run a Batch Subscribe on a List using the MCAPI.php
  4. class and do some basic error checking or handle the return values.
  5. **/
  6. require_once 'inc/MCAPI.class.php';
  7. require_once 'inc/config.inc.php'; //contains apikey
  8.  
  9. $api = new MCAPI($apikey);
  10.  
  11. $batch[] = array('EMAIL'=>$my_email, 'FNAME'=>'Joe', 'INTERESTS'=>'Water,Air');
  12. $batch[] = array('EMAIL'=>$boss_man_email, 'FNAME'=>'Me', 'LNAME'=>'Chimp');
  13.  
  14. $optin = true; //yes, send optin emails
  15. $up_exist = true; // yes, update currently subscribed users
  16. $replace_int = false; // no, add interest, don't replace
  17.  
  18. $vals = $api->listBatchSubscribe($listId,$batch,$optin, $up_exist, $replace_int);
  19.  
  20. if ($api->errorCode){
  21. echo "Batch Subscribe failed!\n";
  22. echo "code:".$api->errorCode."\n";
  23. echo "msg :".$api->errorMessage."\n";
  24. } else {
  25. echo "success:".$vals['success_count']."\n";
  26. echo "errors:".$vals['error_count']."\n";
  27. foreach($vals['errors'] as $val){
  28. echo $val['email_address']. " failed\n";
  29. echo "code:".$val['code']."\n";
  30. echo "msg :".$val['message']."\n";
  31. }}
  32. ?>
  33.  
  34.  
  35.  

[2] xml-rpc_listBatchSubscribe.php

  1. <?php
  2. /**
  3. This Example shows how to use the XML-RPC service to Batch Subscribe many emails
  4. to each of your Lists and do some basic error checking.
  5. Note that we are using the PEAR XML-RPC client and recommend others do as well.
  6.  
  7. Realize that these emails are bogus and being generated - you should not do
  8. that, especially if you turn on the opt-in email.
  9. **/
  10. require_once 'XML/RPC2/Client.php';
  11. require_once 'inc/config.inc.php';
  12.  
  13. try {
  14. $client = XML_RPC2_Client::create($apiUrl);
  15.  
  16. $lists = $client->lists($apikey);
  17.  
  18. foreach ($lists as $list){
  19. echo "\n----[".$list['id']." - ".$list['name']."]----\n";
  20. $batch = array();
  21. for($i = 0; $i < 20; $i++){
  22. $batch[] = array("EMAIL"=>$list['id'].'_'.$i.'@example.com');
  23. }
  24. /**
  25. Note that there is a limit to the number of addresses that can be batch
  26. subscribed. Here we are using 20, which should be fine. We recommend you
  27. not attempt to add more than 5000-10,000 addresses per call to
  28. */
  29. $result = $client->listBatchSubscribe($apikey, $list['id'], $batch, false, false, false);
  30. echo "SUCCESS! \n";
  31. echo "Good : ".$result['success_count']."\n";
  32. echo "Errors: ".$result['error_count']."\n";
  33. foreach($result['errors'] as $err){
  34. echo $err['code'].' - '.$err['message']."\n";
  35. echo "\t".$err['row']['EMAIL']."\n";
  36. }
  37. }
  38. } catch (XML_RPC2_FaultException $e){
  39. echo "ERROR!!!!\n";
  40. echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
  41. }
  42.  
  43. ?>
  44.