API Documentation

« Back to Documentation Overview

listSubscribe – v1.3

 listSubscribe(string apikey, string id, string email_address, array merge_vars, string email_type, bool double_optin, bool update_existing, bool replace_interests, bool send_welcome)

Subscribe the provided email to a list. By default this sends a confirmation email - you will not see new members until the link contained in it is clicked!

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()
email_address the email address to subscribe
merge_vars optional - merges for the email (FNAME, LNAME, etc.) (see examples below for handling "blank" arrays). Note that a merge field can only hold up to 255 bytes. Also, there are a few "special" keys:
stringEMAILset this to change the email address. This is only respected on calls using update_existing or when passed to listUpdateMember()
stringNEW-EMAILset this to change the email address. This is only respected on calls using update_existing or when passed to listUpdateMember(). Required to change via listBatchSubscribe() - EMAIL takes precedence on other calls, though either will work.
arrayGROUPINGSSet Interest Groups by Grouping. Each element in this array should be an array containing the "groups" parameter which contains a comma delimited list of Interest Groups to add. Commas in Interest Group names should be escaped with a backslash. ie, "," => "\," and either an "id" or "name" parameter to specify the Grouping - get from listInterestGroupings()
stringOPTIN_IPSet the Opt-in IP field. Abusing this may cause your account to be suspended. We do validate this and it must not be a private IP address.
stringOPTIN_TIMESet the Opt-in Time field. Abusing this may cause your account to be suspended. We do validate this and it must be a valid date. Use - 24 hour format in GMT, eg "2013-12-30 20:30:00" to be safe. Generally, though, anything strtotime() understands we'll understand - http://us2.php.net/strtotime
arrayMC_LOCATIONSet the member's geographic location. By default if this merge field exists, we'll update using the optin_ip if it exists. If the array contains LATITUDE and LONGITUDE keys, they will be used. NOTE - this will slow down each subscribe call a bit, especially for lat/lng pairs in sparsely populated areas. Currently our automated background processes can and will overwrite this based on opens and clicks.
stringMC_LANGUAGESet the member's language preference. Supported codes are fully case-sensitive and can be found here.
arrayMC_NOTESAdd, update, or delete notes associated with a member. The array must contain either a "note" key (the note to set) or an "id" key (the note id to modify). If the "id" key exists and is valid, an "update" key may be set to "append" (default), "prepend", "replace", or "delete" to handle how we should update existing notes. If a "note" key is passed and the "id" key is not passed or is not valid, a new note will be added. "delete", obviously, will only work with a valid "id" - passing that along with "note" and an invalid "id" is wrong and will be ignored. If this is not an array, it will silently be ignored.
 
Handling Field Data Types - most fields you can just pass a string and all is well. For some, though, that is not the case...
Field values should be formatted as follows:
stringaddressFor the string version of an Address, the fields should be delimited by 2 spaces. Address 2 can be skipped. The Country should be a 2 character ISO-3166-1 code and will default to your default country if not set
arrayaddressFor the array version of an Address, the requirements for Address 2 and Country are the same as with the string version. Then simply pass us an array with the keys addr1, addr2, city, state, zip, country and appropriate values for each
 
stringbirthdaythe month and day of birth, passed as MM/DD
arraybirthdaythe month and day of birth, passed in an array using the keys month and day
 
stringdateuse YYYY-MM-DD to be safe. Generally, though, anything strtotime() understands we'll understand - http://us2.php.net/strtotime
stringdropdowncan be a normal string - we will validate that the value is a valid option
stringimagemust be a valid, existing url. we will check its existence
stringmulti_choicecan be a normal string - we will validate that the value is a valid option
doublenumberpass in a valid number - anything else will turn in to zero (0). Note, this will be rounded to 2 decimal places
stringphoneIf your account has the US Phone numbers option set, this must be in the form of NPA-NXX-LINE (404-555-1212). If not, we assume an International number and will simply set the field with what ever number is passed in.
stringwebsiteThis is a standard string, but we will verify that it looks like a valid URL
stringzipA U.S. zip code. We'll validate this is a 4 or 5 digit number.
email_type optional - email type preference for the email (html or text - defaults to html)
double_optin optional - flag to control whether a double opt-in confirmation message is sent, defaults to true. Abusing this may cause your account to be suspended.
update_existing optional - flag to control whether existing subscribers should be updated instead of throwing an error, defaults to false
replace_interests optional - flag to determine whether we replace the interest groups with the groups provided or we add the provided groups to the member's interest groups (optional, defaults to true)
send_welcome optional - if your double_optin is false and this is true, we will send your lists Welcome Email if this subscribe succeeds - this will *not* fire if we end up updating an existing subscriber. If double_optin is true, this has no effect. defaults to false.
Returns
boolean true on success, false on failure. When using MCAPI.class.php, the value can be tested and error messages pulled from the MCAPI object (see below)

Examples (3)

download example code

[1] mcapi_listSubscribe.php

  1. <?php
  2. /**
  3. This Example shows how to Subscribe a New Member to a List using the MCAPI.php 
  4. class and do some basic error checking.
  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. $merge_vars = array('FNAME'=>'Test', 'LNAME'=>'Account', 
  12.                   'GROUPINGS'=>array(
  13.                         array('name'=>'Your Interests:', 'groups'=>'Bananas,Apples'),
  14.                         array('id'=>22, 'groups'=>'Trains'),
  15.                         )
  16.                     );
  17.  
  18. // By default this sends a confirmation email - you will not see new members
  19. // until the link contained in it is clicked!
  20. $retval = $api->listSubscribe( $listId, $my_email, $merge_vars );
  21.  
  22. if ($api->errorCode){
  23. 	echo "Unable to load listSubscribe()!\n";
  24. 	echo "\tCode=".$api->errorCode."\n";
  25. 	echo "\tMsg=".$api->errorMessage."\n";
  26. } else {
  27.     echo "Subscribed - look for the confirmation email!\n";
  28. }
  29.  
  30. ?>
  31.  

[2] json_listSubscribe.php

  1. <?php
  2. require_once 'inc/config.inc.php'; //contains apikey
  3.  
  4. $merges = array('FNAME'=>'Dave', 'LNAME'=>'Gilmour',
  5.                 'address1'=>array('addr1'=>'12335 Hope St', 'city'=>'Dallas', 'state'=>'TX', 'zip'=>'76058'),
  6.                 'phone' => '412392222522255',
  7.                 'MMERGE5'=>'http://www.mailchimp.com/',
  8.                 'OPTIN_IP'=>'8.8.4.4',
  9.                 'GROUPINGS'=>array(
  10.                               array('name'=>'test', 'groups'=>'group name'),
  11.                              ),
  12.                 'MC_LOCATION'=>array('LATITUDE'=>34.0413, 'LONGITUDE'=>-84.3473)
  13. );
  14.  
  15.  
  16. $double_optin=true;
  17. $update_existing=false;
  18. $replace_interests=true;
  19. $send_welcome=false;
  20. $email_type = 'html';            
  21. $data = array(
  22.         'email_address'=>$email,
  23.         'apikey'=>$apikey,
  24.         'merge_vars' => $merges,
  25.         'id' => $listId,
  26.         'double_optin' => $double_optin,
  27.         'update_existing' => $update_existing,
  28.         'replace_interests' => $replace_interests,
  29.         'send_welcome' => $send_welcome,
  30.         'email_type' => $email_type
  31.     );
  32. $payload = json_encode($data);
  33.  
  34. //replace us2 with your actual datacenter
  35. $submit_url = "http://us2.api.mailchimp.com/1.3/?method=listSubscribe";
  36.  
  37. $ch = curl_init();
  38. curl_setopt($ch, CURLOPT_URL, $submit_url);
  39. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  40. curl_setopt($ch, CURLOPT_POST, true);
  41. curl_setopt($ch, CURLOPT_POSTFIELDS, urlencode($payload));
  42.  
  43. $result = curl_exec($ch);
  44. curl_close ($ch);
  45. $data = json_decode($result);
  46. if ($data->error){
  47.     echo $data->code .' : '.$data->error."\n";
  48. } else {
  49.     echo "success, look for the confirmation message\n";
  50. }
  51. ?> 
  52.  

[3] xml-rpc_listSubscribe.php

  1. <?php
  2. /**
  3. This Example shows how to Subscribe a New Member to a List using XML-RPC.
  4. Note that we are using the PEAR XML-RPC client and recommend others do as well.
  5. **/
  6. require_once 'XML/RPC2/Client.php';
  7. require_once 'inc/config.inc.php';
  8. try {
  9.     $client = XML_RPC2_Client::create($apiUrl);
  10.  
  11.     // Note that the same blank array() restriction for the merge_vars
  12.     // does not apply here as XML-RPC will handle it unless you use a null value
  13.     $merges = array('FNAME'=>'Test', 'LNAME'=>'Account', 
  14.                     'INTERESTS'=>'Dogs,Horses');
  15.     // By default this sends a confirmation email - you will not see new members
  16.     // until the link contained in it is clicked!
  17.     $result = $client->listSubscribe($apikey, $listId, $my_email, $merges, 'html', false);
  18.     echo "SUCCESS!\n";
  19.     echo "Returned: ".$result."\n";
  20. } catch (XML_RPC2_FaultException $e){
  21. 	echo "ERROR!!!!\n";
  22. 	echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
  23. }
  24. ?>
  25.