MailChimp API v3.0 is now live!
Prior versions will no longer be supported after 2016, so all API users should begin transitioning to v3.0.
Check out the API v3.0 Documentation for more details.
« Back to Documentation Overview

/lists/subscribe.format - v2.0

This method is available for API Keys belonging to users with the following roles: manager, admin, owner
Take a look at this article to learn more about the different access levels for a MailChimp account.

subscribe(string apikey, string id, struct email, struct merge_vars, string email_type, bool double_optin, bool update_existing, bool replace_interests, bool send_welcome)
When using a wrapper or XML-RPC, this is generally the parameter order. When building JSON objects or serialized HTTP requests parameter order does not matter

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!

apikey string a valid API Key for your user account. Get by visiting your API dashboard
id string the list id to connect to. Get by calling lists/list()
email struct a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
email string an email address - for new subscribers obviously this should be used
euid string the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
leid string the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
merge_vars struct optional - 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:
new-email string set this to change the email address. This is only respected on calls using update_existing or when passed to lists/update.
groupings array of Interest Grouping structs. Each should contain:
id int Grouping "id" from lists/interest-groupings (either this or name must be present) - this id takes precedence and can't change (unlike the name)
name string Grouping "name" from lists/interest-groupings (either this or id must be present)
groups array an array of valid group names for this grouping.
optin_ip string Set 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.
optin_time string Set 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 -
mc_location struct Set the member's geographic location either by optin_ip or geo data.
latitude string use the specified latitude (longitude must exist for this to work)
longitude string use the specified longitude (latitude must exist for this to work)
anything string if this (or any other key exists here) we'll try to use the optin ip. 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.
mc_language string Set the member's language preference. Supported codes are fully case-sensitive and can be found here.
mc_notes array of structs for managing notes - it may contain:
note string the note to set. this is required unless you're deleting a note
id int the note id to operate on. not including this (or using an invalid id) causes a new note to be added
action string 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. "delete", obviously, will only work with a valid "id" - passing that along with "note" and an invalid "id" is wrong and will 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:
address string 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
address array 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
birthday string the month and day of birth, passed as MM/DD
date string use YYYY-MM-DD to be safe. Generally, though, anything strtotime() understands we'll understand -
dropdown string can be a normal string - we will validate that the value is a valid option
image string must be a valid, existing url. we will check its existence
multi_choice string can be a normal string - we will validate that the value is a valid option
number double pass in a valid number - anything else will turn in to zero (0). Note, this will be rounded to 2 decimal places
phone string 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.
website string This is a standard string, but we will verify that it looks like a valid URL
zip string A U.S. zip code. We'll validate this is a 4 or 5 digit number.
the month and day of birth, passed in an array using the keys month and day
email_type string optional - optional email type preference for the email (html or text - defaults to html)
double_optin bool optional - 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 bool optional - optional flag to control whether existing subscribers should be updated instead of throwing an error, defaults to false
replace_interests bool optional - 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 bool optional - 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.
Return Value
struct the ids for this subscriber
string email the email address added
string euid the email unique id
string leid the list member's truly unique id

Example Request JSON

{"apikey": "example apikey", "id": "example id", "email":{"email": "example email", "euid": "example euid", "leid": "example leid"},"merge_vars":{"new-email": "example new-email", "groupings":[{"id":42,"name": "example name", "groups":["..."]}],"optin_ip": "example optin_ip", "optin_time": "example optin_time", "mc_location":{"latitude": "example latitude", "longitude": "example longitude", "anything": "example anything"},"mc_language": "example mc_language", "mc_notes":[{"note": "example note", "id":42,"action": "example action"}]},"email_type": "example email_type", "double_optin":true,"update_existing":true,"replace_interests":true,"send_welcome":true}

Example Response JSON

{"email": "example email", "euid": "example euid", "leid": "example leid"}

Example Error Response JSON

{"status": "error", "code":-99,"name": "Unknown_Exception", "error": "An unknown error occurred processing your request. Please try again later."}
Method-specific Errors
API-wide Errors
Invalid_ApiKey The API Key provided is invalid, revoked, you're in the wrong data center, or whatever the error message says.
User_Disabled The account being accessed has been disabled - more detail in the actual message returned.
User_InvalidRole The account being accessed does not have permission to access the API method
Too_Many_Connections You didn't pay attention to this
User_UnderMaintenance The account being access is currently under temporary maintenance
User_InvalidAction The account being accessed has not been approved for some action - more detail in the actual message returned.
ValidationError The parameters passed to the API call are invalid or not provided when required