Mailchimp API

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 calling login()

id	the list id to connect to. Get by calling lists()

email_address

the email address to subscribe

merge_vars

array of 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 characters. Also, there are 2 "special" keys: string INTERESTS Set Interest Groups by passing a field named "INTERESTS" that contains a comma delimited list of Interest Groups to add. Commas in Interest Group names should be escaped with a backslash. ie, "," => "\," string OPTINIP Set the Opt-in IP fields. Abusing this may cause your account to be suspended. We do validate this and it must not be a private IP address.   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: string address For 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 array address For 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   string date use YYYY-MM-DD to be safe. Generally, though, anything strtotime() understands we'll understand - http://us2.php.net/strtotime string dropdown can be a normal string - we will validate that the value is a valid option string image must be a valid, existing url. we will check its existence string multi_choice can be a normal string - we will validate that the value is a valid option double number pass in a valid number - anything else will turn in to zero (0). Note, this will be rounded to 2 decimal places string phone If 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. string website This is a standard string, but we will verify that it looks like a valid URL

email_type

optional - email type preference for the email (html, text, or mobile 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 a existing subscribers should be updated instead of throwing and error

replace_interests

- 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

- 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 (2)

download example code

[1] mcapi_listSubscribe.php

<?php
/**
This Example shows how to Subscribe a New Member to a List using the MCAPI.php 
class and do some basic error checking.
**/
require_once 'inc/MCAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MCAPI($apikey);
 
/** 
Note that if you are not passing merge_vars, you will still need to
pass a "blank" array. That should be either:
	$merge_vars = array('');
	   - or -
	$merge_vars = '';
 
Specifically, this will fail:
	$merge_vars = array();
 
Or pass the proper data as below...
*/
$merge_vars = array('FNAME'=>'Test', 'LNAME'=>'Account', 
                    'INTERESTS'=>'');
// By default this sends a confirmation email - you will not see new members
// until the link contained in it is clicked!
$retval = $api->listSubscribe( $listId, $my_email, $merge_vars );
 
if ($api->errorCode){
	echo "Unable to load listSubscribe()!\n";
	echo "\tCode=".$api->errorCode."\n";
	echo "\tMsg=".$api->errorMessage."\n";
} else {
    echo "Returned: ".$retval."\n";
}
 
 

[2] xml-rpc_listSubscribe.php

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