listBatchSubscribe – v1.2

 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. If you are using a serialized version of the API, we strongly suggest that you only run this method as a POST request, and not a GET request. Maximum batch sizes vary based on the amount of data in each record, though you should cap them at 5k - 10k records, depending on your experience. These calls are also long, so be sure you increase your timeout values.

Section
List Related

Parameters
apikey	a valid API Key for your user account. 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, text, or mobile)
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
integer	success_count	Number of email addresses that were succesfully added/updated
integer	error_count	Number of email addresses that failed during addition/updating
array	errors	Array 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

<?php
/**
This Example shows how to run a Batch Subscribe on a List using the MCAPI.php 
class and do some basic error checking or handle the return values.
**/
require_once 'inc/MCAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MCAPI($apikey);
 
$batch[] = array('EMAIL'=>$my_email, 'FNAME'=>'Joe', 'INTERESTS'=>'Water,Air');
$batch[] = array('EMAIL'=>$boss_man_email, 'FNAME'=>'Me', 'LNAME'=>'Chimp');
 
$optin = true; //yes, send optin emails
$up_exist = true; // yes, update currently subscribed users
$replace_int = false; // no, add interest, don't replace
 
$vals = $api->listBatchSubscribe($listId,$batch,$optin, $up_exist, $replace_int);
 
if ($api->errorCode){
    echo "Batch Subscribe failed!\n";
	echo "code:".$api->errorCode."\n";
	echo "msg :".$api->errorMessage."\n";
} else {
	echo "success:".$vals['success_count']."\n";
	echo "errors:".$vals['error_count']."\n";
	foreach($vals['errors'] as $val){
		echo $val['email_address']. " failed\n";
		echo "code:".$val['code']."\n";
		echo "msg :".$val['message']."\n";
	}}
?> 
 
 
 

[2] xml-rpc_listBatchSubscribe.php

<?php
/**
This Example shows how to use the XML-RPC service to Batch Subscribe many emails 
to each of your Lists and do some basic error checking.
Note that we are using the PEAR XML-RPC client and recommend others do as well.
 
Realize that these emails are bogus and being generated - you should not do 
that, especially if you turn on the opt-in email.
**/
require_once 'XML/RPC2/Client.php';
require_once 'inc/config.inc.php';
 
try {
    $client = XML_RPC2_Client::create($apiUrl);
 
    $lists = $client->lists($apikey);
 
    foreach ($lists as $list){
	    echo "\n----[".$list['id']." - ".$list['name']."]----\n";
	    $batch = array();
	    for($i = 0; $i < 20; $i++){
		    $batch[] = array("EMAIL"=>$list['id'].'_'.$i.'@example.com');
	    }	
	    /**
	    Note that there is a limit to the number of addresses that can be batch 
	    subscribed. Here we are using 20, which should be fine. We recommend you
	    not attempt to add more than 5000-10,000 addresses per call to 
	    listBatchSubscribe()
	    */
	    $result = $client->listBatchSubscribe($apikey, $list['id'], $batch, false, false, false);
	    echo "SUCCESS! \n";
	    echo "Good  : ".$result['success_count']."\n";
	    echo "Errors: ".$result['error_count']."\n";
	    foreach($result['errors'] as $err){
	        echo $err['code'].' - '.$err['message']."\n";
	        echo "\t".$err['row']['EMAIL']."\n";
	    }
    }
} catch (XML_RPC2_FaultException $e){
    echo "ERROR!!!!\n";
    echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
}
 
?>