MailChimp API v1.2 Documentation

view the change log | jump down to the methods

Submit URL & Parameters

The submit URL for the return formats supported are relatively the same.

NOTICE: Beginning in September 2009, our API endpoints are datacenter specific. If a datacenter prefix is not used, then "us1" will be assumed. API Wrappers are being updated to auto-switch based on API Keys. If you are not using a wrapper, you you will need to hard code the endpoint into your app.

That said, use these and replace <dc> with the portion after the dash in your API Key. e.g. "us1", "us2", "uk1", etc.

For XML-RPC, simply tell your client to connect to:
http://<dc>.api.mailchimp.com/1.2/
For Serialized JSON, use:
http://<dc>.api.mailchimp.com/1.2/?output=json&method=SOME-METHOD&[other parameters]
For Serialized XML, use:
http://<dc>.api.mailchimp.com/1.2/?output=xml&method=SOME-METHOD&[other parameters]
For Serialized PHP, use:
http://<dc>.api.mailchimp.com/1.2/?output=php&method=SOME-METHOD&[other parameters]
For Serialized LOLCODE, use:
http://<dc>.api.mailchimp.com/1.2/?output=lolcode&method=SOME-METHOD&[other parameters]
Note that for the Serialized versions, method is the method from our API you are calling and [other parameters] are the parameters the documentation calls for. Additionally, either GET or POST requests may be used for the serialized versions, though the method currently must always be a GET parameter.

HTTPS / Secure Connections

HTTPS is 100% supported with valid, signed certificates for all API methods regardless of whether your calls use XML-RPC or the Serialized GET/POST. Those manually coding Submit URLs can simply change the http to https in the URL (make sure your connection library supports HTTPS!). Some API Wrappers have switches to turn HTTPS on - others may require hacking at their source or contacting the author to include support.

Questions? Problems?

Have you run into difficulties or a method just doesn't seem to work right? Check out our API Support options here and we'll be happy to assist you.

Version:1.2


Error Codes
static array

$exceptions

A mapping of known Exception classes to numerical codes that will be returned when errors occur.

 
 Campaign Related Methods  
static

campaignContent(string apikey, string cid, bool for_archive)

Get the content (both html and text) for a campaign either as it would appear in the campaign archive or as the raw, original content

static

campaignCreate(string apikey, string type, array options, array content, array segment_opts, array type_opts)

Create a new draft campaign to send

static

campaignDelete(string apikey, string cid)

Delete a campaign.

static

campaignEcommAddOrder(string apikey, array order)

Attach Ecommerce Order Information to a Campaign.

static

campaignFolders(string apikey)

List all the folders for a user account

static

campaignPause(string apikey, string cid)

Pause an AutoResponder orRSS campaign from sending

static

campaignReplicate(string apikey, string cid)

Replicate a campaign.

static

campaignResume(string apikey, string cid)

Resume sending an AutoResponder or RSS campaign

static

campaignSchedule(string apikey, string cid, string schedule_time, string schedule_time_b)

Schedule a campaign to be sent in the future

static

campaignSegmentTest(string apikey, string list_id, array options)

Allows one to test their segmentation rules before creating a campaign using them

static

campaignSendNow(string apikey, string cid)

Send a given campaign immediately

static

campaignSendTest(string apikey, string cid, array test_emails, string send_type)

Send a test of this campaign to the provided email address

static

campaignShareReport(string apikey, string cid, array opts)

Get the URL to a customized VIP Report for the specified campaign and optionally send an email to someone with links to it.

static

campaignTemplates(string apikey)

Retrieve all templates defined for your user account

static

campaignUnschedule(string apikey, string cid)

Unschedule a campaign that is scheduled to be sent in the future

static

campaignUpdate(string apikey, string cid, string name, mixed value)

Update just about any setting for a campaign that has not been sent.

static

campaigns(string apikey, array filters, integer start, integer limit)

Get the list of campaigns and their details matching the specified filters

 Campaign Stats Methods  
static

campaignAbuseReports(string apikey, string cid, string since, integer start, integer limit)

Get all email addresses that complained about a given campaign

static

campaignAdvice(string apikey, string cid)

Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best suited for display in customized reports pages.

static

campaignAnalytics(string apikey, string cid)

Retrieve the Google Analytics data we've collected for this campaign.

static

campaignBounceMessages(string apikey, string cid, integer start, integer limit, string since)

Retrieve the full bounce messages for the given campaign.

static

campaignClickStats(string apikey, string cid)

Get an array of the urls being tracked, and their click counts for a given campaign

static

campaignEcommOrders(string apikey, string cid, integer start, integer limit, string since)

Retrieve the Ecommerce Orders tracked by campaignEcommAddOrder()

static

campaignEmailDomainPerformance(string apikey, string cid)

Get the top 5 performing email domains for this campaign.

static

campaignHardBounces(string apikey, string cid, integer start, integer limit)

Get all email addresses with Hard Bounces for a given campaign

static

campaignSoftBounces(string apikey, string cid, integer start, integer limit)

Get all email addresses with Soft Bounces for a given campaign

static

campaignStats(string apikey, string cid)

Given a list and a campaign, get all the relevant campaign statistics (opens, bounces, clicks, etc.)

static

campaignUnsubscribes(string apikey, string cid, integer start, integer limit)

Get all unsubscribed email addresses for a given campaign

 Campaign AIM Methods  
static

campaignClickDetailAIM(string apikey, string cid, string url, integer start, integer limit)

Return the list of email addresses that clicked on a given url, and how many times they clicked

static

campaignEmailStatsAIM(string apikey, string cid, string email_address)

Given a campaign and email address, return the entire click and open history with timestamps, ordered by time

static

campaignEmailStatsAIMAll(string apikey, string cid, integer start, integer limit)

Given a campaign and correct paging limits, return the entire click and open history with timestamps, ordered by time, for every user a campaign was delivered to.

static

campaignNotOpenedAIM(string apikey, string cid, integer start, integer limit)

Retrieve the list of email addresses that did not open a given campaign

static

campaignOpenedAIM(string apikey, string cid, integer start, integer limit)

Retrieve the list of email addresses that opened a given campaign with how many times they opened - note: this AIM function is free and does not actually require the AIM module to be installed

 Helper Methods  
static

createFolder(string apikey, string name)

Create a new folder to file campaigns in

static

generateText(string apikey, string type, mixed content)

Have HTML content auto-converted to a text-only format.

static

getAccountDetails(string apikey)

Retrieve lots of account information including payments made, plan info, some account stats, installed modules, contact info, and more.

static

getAffiliateInfo(string apikey)

DEPRECATED: Retrieve your User Unique Id and your Affiliate link to display/use for Monkey Rewards.

static

inlineCss(string apikey, string html, bool strip_css)

Send your HTML content to have the CSS inlined and optionally remove the original styles.

static

ping(string apikey)

"Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything is good.

 List Related Methods  
static

listAbuseReports(string apikey, string id, integer start, integer limit, string since)

Get all email addresses that complained about a given campaign

static

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

static

listBatchUnsubscribe(string apikey, string id, array emails, boolean delete_member, boolean send_goodbye, boolean send_notify)

Unsubscribe a batch of email addresses to a list

static

listGrowthHistory(string apikey, string id)

Access the Growth History by Month for a given list.

static

listInterestGroupAdd(string apikey, string id, string group_name)

Add a single Interest Group - if interest groups for the List are not yet enabled, adding the first group will automatically turn them on.

static

listInterestGroupDel(string apikey, string id, string group_name)

Delete a single Interest Group - if the last group for a list is deleted, this will also turn groups for the list off.

static

listInterestGroupUpdate(string apikey, string id, string old_name, string new_name)

Change the name of an Interest Group

static

listInterestGroups(string apikey, string id)

Get the list of interest groups for a given list, including the label and form information

static

listMemberInfo(string apikey, string id, string email_address)

Get all the information for a particular member of a list

static

listMembers(string apikey, string id, string status, string since, integer start, integer limit)

Get all of the list members for a list that are of a particular status

static

listMergeVarAdd(string apikey, string id, string tag, string name, array req)

Add a new merge tag to a given list

static

listMergeVarDel(string apikey, string id, string tag)

Delete a merge tag from a given list and all its members.

static

listMergeVarUpdate(string apikey, string id, string tag, array options)

Update most parameters for a merge tag on a given list.

static

listMergeVars(string apikey, string id)

Get the list of merge tags for a given list, including their name, tag, and required setting

static

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

Subscribe the provided email to a list.

static

listUnsubscribe(string apikey, string id, string email_address, boolean delete_member, boolean send_goodbye, boolean send_notify)

Unsubscribe the given email address from the list

static

listUpdateMember(string apikey, string id, string email_address, array merge_vars, string email_type, boolean replace_interests)

Edit the email address, merge fields, and interest groups for a list member

static

listWebhookAdd(string apikey, string id, string url, array actions, array sources)

Add a new Webhook URL for the given list

static

listWebhookDel(string apikey, string id, string url)

Delete an existing Webhook URL from a given list

static

listWebhooks(string apikey, string id)

Return the Webhooks configured for the given list

static

lists(string apikey)

Retrieve all of the lists defined for your user account

 Security Related Methods  
static

apikeyAdd(string username, string password, string apikey)

Add an API Key to your account.

static

apikeyExpire(string username, string password, string apikey)

Expire a Specific API Key.

static

apikeys(string username, string password, string apikey, boolean expired)

Retrieve a list of all MailChimp API Keys for this User

static

login(string username, string password)

DEPRECATED: Log into the MailChimp API and return an API Key.