MailChimp API v2.0 Documentation

API Endpoints

All API URLs listed in this documentation are relative to https://<dc>.api.mailchimp.com/2.0/. For example, the /helper/ping API call is reachable at https://<dc>.api.mailchimp.com/2.0/helper/ping.

Important: Our API endpoints (or submit URLs) are datacenter specific. If a datacenter prefix is not used, then "us1" is assumed. Most API Wrappers have been updated to auto-switch based on API Keys. If you are not using a wrapper, you will need to hard code the endpoint into your app.

As seen above, the generic format for the API endpoint is:

https://<dc>.api.mailchimp.com/2.0/

Where <dc> should be replaced with the portion after the dash in your API Key. e.g. "us1", "us2", "uk1", etc. A solid example - say your API Key is myapikey-us2. You are in us2, so your API Endpoint would be:

https://us2.api.mailchimp.com/2.0/

RESTful

The MailChimp API is a mostly RESTful API. Known caveats:

  • All API calls should be made with HTTP POST.
  • You can consider any non-200 HTTP response code an error - the returned data will contain more detailed information
  • All methods are accessed via: https://dc.api.mailchimp.com/2.0/SECTION/SOME-METHOD.OUTPUT_FORMAT

Passing Request Data

Request data is passed to the API by POSTing JSON objects to the API endpoints with the appropriate parameters. The documentation for each API call will contain more detail on the parameters accepted by the call. As an alternative, you can also use HTTP POST parameters, just like submitting an HTML FORM, but JSON objects are recommended.

Output Formats

We support three output formats. To use any of them, simply replace the file extension in the API URL (OUTPUT_FORMAT above) with one of:

  • json (default)
  • xml
  • php
The response data for each call will the be encoded in the specified format. Regardless of the output format desired, inputs are only accepted as JSON objects or HTTP POST parameters.

HTTPS / Secure Connections

HTTPS is required. We provide a valid, signed certificate for all API methods regardless of whether your calls use XML-RPC or the Serialized POST (fine, GET too). 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.

Noteworty Quriks

Throughout this API, a return value of an empty object "{}" will be represented by an empty array "[]". We recognize the headache this causes to our friends in statically-typed languages, but changing the behavior would be backwards incompatible for versions up to 2.0. This problem will be resolved in the next version after 2.0

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

Method Sections

Campaigns Related
Ecomm Related
Folders Related
Gallery Related
Lists Related
Helper Related
Reports Related
Templates Related
Users Related
Vip Related
Goal Related
Conversations Related
Campaigns Related Methods  

campaigns/content (string apikey, string cid, struct options)

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

campaigns/create (string apikey, string type, struct options, struct content, struct segment_opts, struct type_opts)

Create a new draft campaign to send. You can not have more than 32,000 campaigns in your account.

campaigns/delete (string apikey, string cid)

Delete a campaign. Seriously, "poof, gone!" - be careful! Seriously, no one can undelete these.

campaigns/list (string apikey, struct filters, int start, int limit, string sort_field, string sort_dir)

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

campaigns/pause (string apikey, string cid)

Pause an AutoResponder or RSS campaign from sending

campaigns/ready (string apikey, string cid)

Returns information on whether a campaign is ready to send and possible issues we may have detected with it - very similar to the confirmation step in the app.

campaigns/replicate (string apikey, string cid)

Replicate a campaign.

campaigns/resume (string apikey, string cid)

Resume sending an AutoResponder or RSS campaign

campaigns/schedule-batch (string apikey, string cid, string schedule_time, int num_batches, int stagger_mins)

Schedule a campaign to be sent in batches sometime in the future. Only valid for "regular" campaigns

campaigns/schedule (string apikey, string cid, string schedule_time, string schedule_time_b)

Schedule a campaign to be sent in the future

campaigns/segment-test (string apikey, string list_id, struct options)

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

campaigns/send (string apikey, string cid)

Send a given campaign immediately. For RSS campaigns, this will "start" them.

campaigns/send-test (string apikey, string cid, array test_emails, string send_type)

Send a test of this campaign to the provided email addresses

campaigns/template-content (string apikey, string cid)

Get the HTML template content sections for a campaign. Note that this will return very jagged, non-standard results based on the template a campaign is using. You only want to use this if you want to allow editing template sections in your application.

campaigns/unschedule (string apikey, string cid)

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

campaigns/update (string apikey, string cid, string name, array value)

Update just about any setting besides type for a campaign that has not been sent. See campaigns/create() for details. Caveats:

  • If you set a new list_id, all segmentation options will be deleted and must be re-added.
  • If you set template_id, you need to follow that up by setting it's 'content'
  • If you set segment_opts, you should have tested your options against campaigns/segment-test().
  • To clear/unset segment_opts, pass an empty string or array as the value. Various wrappers may require one or the other.

Ecomm Related Methods  

ecomm/order-add (string apikey, struct order)

Import Ecommerce Order Information to be used for Segmentation. This will generally be used by ecommerce package plugins provided by us or by 3rd part system developers.

ecomm/order-del (string apikey, string store_id, string order_id)

Delete Ecommerce Order Information used for segmentation. This will generally be used by ecommerce package plugins that we provide or by 3rd part system developers.

ecomm/orders (string apikey, string cid, int start, int limit, string since)

Retrieve the Ecommerce Orders for an account

Folders Related Methods  

folders/add (string apikey, string name, string type)

Add a new folder to file campaigns, autoresponders, or templates in

folders/del (string apikey, int fid, string type)

Delete a campaign, autoresponder, or template folder. Note that this will simply make whatever was in the folder appear unfiled, no other data is removed

folders/list (string apikey, string type)

List all the folders of a certain type

folders/update (string apikey, int fid, string name, string type)

Update the name of a folder for campaigns, autoresponders, or templates

Lists Related Methods  

lists/abuse-reports (string apikey, string id, int start, int limit, string since)

Get all email addresses that complained about a campaign sent to a list

lists/activity (string apikey, string id)

Access up to the previous 180 days of daily detailed aggregated activity stats for a given list. Does not include AutoResponder activity.

lists/batch-subscribe (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.

lists/batch-unsubscribe (string apikey, string id, array batch, boolean delete_member, boolean send_goodbye, boolean send_notify)

Unsubscribe a batch of email addresses from a list

lists/clients (string apikey, string id)

Retrieve the clients that the list's subscribers have been tagged as being used based on user agents seen. Made possible by user-agent-string.info

lists/growth-history (string apikey, string id)

Access the Growth History by Month in aggregate or for a given list.

lists/interest-group-add (string apikey, string id, string group_name, int grouping_id)

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

lists/interest-group-del (string apikey, string id, string group_name, int grouping_id)

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

lists/interest-group-update (string apikey, string id, string old_name, string new_name, int grouping_id)

Change the name of an Interest Group

lists/interest-grouping-add (string apikey, string id, string name, string type, array groups)

Add a new Interest Grouping - if interest groups for the List are not yet enabled, adding the first grouping will automatically turn them on.

lists/interest-grouping-del (string apikey, int grouping_id)

Delete an existing Interest Grouping - this will permanently delete all contained interest groups and will remove those selections from all list members

lists/interest-grouping-update (string apikey, int grouping_id, string name, string value)

Update an existing Interest Grouping

lists/interest-groupings (string apikey, string id, bool counts)

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

lists/list (string apikey, struct filters, int start, int limit, string sort_field, string sort_dir)

Retrieve all of the lists defined for your user account

lists/locations (string apikey, string id)

Retrieve the locations (countries) that the list's subscribers have been tagged to based on geocoding their IP address

lists/member-activity (string apikey, string id, array emails)

Get the most recent 100 activities for particular list members (open, click, bounce, unsub, abuse, sent to, etc.)

lists/member-info (string apikey, string id, array emails)

Get all the information for particular members of a list

lists/members (string apikey, string id, string status, struct opts)

Get all of the list members for a list that are of a particular status and potentially matching a segment. This will cause locking, so don't run multiples at once. Are you trying to get a dump including lots of merge data or specific members of a list? If so, checkout the List Export API

lists/merge-var-add (string apikey, string id, string tag, string name, struct options)

Add a new merge tag to a given list

lists/merge-var-del (string apikey, string id, string tag)

Delete a merge tag from a given list and all its members. Seriously - the data is removed from all members as well! Note that on large lists this method may seem a bit slower than calls you typically make.

lists/merge-var-reset (string apikey, string id, string tag)

Completely resets all data stored in a merge var on a list. All data is removed and this action can not be undone.

lists/merge-var-set (string apikey, string id, string tag, string value)

Sets a particular merge var to the specified value for every list member. Only merge var ids 1 - 30 may be modified this way. This is generally a dirty method unless you're fixing data since you should probably be using default_values and/or conditional content. as with lists/merge-var-reset(), this can not be undone.

lists/merge-var-update (string apikey, string id, string tag, struct options)

Update most parameters for a merge tag on a given list. You cannot currently change the merge type

lists/merge-vars (string apikey, array id)

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

lists/segment-add (string apikey, string id, struct opts)

Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments are not tied to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance. When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation options), though performance may degrade at that point. Saved Segments (called "auto-updating" in the app) are essentially just the match+conditions typically used.

lists/segment-del (string apikey, string id, int seg_id)

Delete a segment. Note that this will, of course, remove any member affiliations with any static segments deleted

lists/segment-test (string apikey, string list_id, struct options)

Allows one to test their segmentation rules before creating a campaign using them - this is no different from campaigns/segment-test() and will eventually replace it. For the time being, the crazy segmenting condition documentation will continue to live over there.

lists/segment-update (string apikey, string id, int seg_id, struct opts)

Update an existing segment. The list and type can not be changed.

lists/segments (string apikey, string id, string type)

Retrieve all of Segments for a list.

lists/static-segment-add (string apikey, string id, string name)

Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments are not tied to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance. When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation options), though performance may degrade at that point.

lists/static-segment-del (string apikey, string id, int seg_id)

Delete a static segment. Note that this will, of course, remove any member affiliations with the segment

lists/static-segment-members-add (string apikey, string id, int seg_id, array batch)

Add list members to a static segment. It is suggested that you limit batch size to no more than 10,000 addresses per call. Email addresses must exist on the list in order to be included - this will not subscribe them to the list!

lists/static-segment-members-del (string apikey, string id, int seg_id, array batch)

Remove list members from a static segment. It is suggested that you limit batch size to no more than 10,000 addresses per call. Email addresses must exist on the list in order to be removed - this will not unsubscribe them from the list!

lists/static-segment-reset (string apikey, string id, int seg_id)

Resets a static segment - removes all members from the static segment. Note: does not actually affect list member data

lists/static-segments (string apikey, string id, boolean get_counts, int start, int limit)

Retrieve all of the Static Segments for a list.

lists/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)

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!

lists/unsubscribe (string apikey, string id, struct email, boolean delete_member, boolean send_goodbye, boolean send_notify)

Unsubscribe the given email address from the list

lists/update-member (string apikey, string id, struct email, struct merge_vars, string email_type, boolean replace_interests)

Edit the email address, merge fields, and interest groups for a list member. If you are doing a batch update on lots of users, consider using lists/batch-subscribe() with the update_existing and possible replace_interests parameter.

lists/webhook-add (string apikey, string id, string url, struct actions, struct sources)

Add a new Webhook URL for the given list

lists/webhook-del (string apikey, string id, string url)

Delete an existing Webhook URL from a given list

lists/webhooks (string apikey, string id)

Return the Webhooks configured for the given list

Helper Related Methods  

helper/account-details (string apikey, array exclude)

Retrieve lots of account information including payments made, plan info, some account stats, installed modules, contact info, and more. No private information like Credit Card numbers is available.

helper/campaigns-for-email (string apikey, struct email, struct options)

Retrieve minimal data for all Campaigns a member was sent

helper/chimp-chatter (string apikey)

Return the current Chimp Chatter messages for an account.

helper/generate-text (string apikey, string type, struct content)

Have HTML content auto-converted to a text-only format. You can send: plain HTML, an existing Campaign Id, or an existing Template Id. Note that this will not save anything to or update any of your lists, campaigns, or templates. It's also not just Lynx and is very fine tuned for our template layouts - your mileage may vary.

helper/inline-css (string apikey, string html, bool strip_css)

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

helper/lists-for-email (string apikey, struct email)

Retrieve minimal List data for all lists a member is subscribed to.

helper/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. Note than unlike most all of our methods, we don't throw an Exception if we are having issues. You will simply receive a different string back that will explain our view on what is going on.

helper/search-campaigns (string apikey, string query, int offset, string snip_start, string snip_end)

Search all campaigns for the specified query terms

helper/search-members (string apikey, string query, string id, int offset)

Search account wide or on a specific list using the specified query terms

helper/verified-domains (string apikey)

Retrieve all domain verification records for an account

Reports Related Methods  

reports/abuse (string apikey, string cid, struct opts)

Get all email addresses that complained about a given campaign

reports/advice (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. Note: some messages will contain HTML - clean tags as necessary

reports/bounce-message (string apikey, string cid, struct email)

Retrieve the most recent full bounce message for a specific email address on the given campaign. Messages over 30 days old are subject to being removed

reports/bounce-messages (string apikey, string cid, struct opts)

Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts of data depending on how large the campaign was and how much cruft the bounce provider returned. Also, messages over 30 days old are subject to being removed

reports/click-detail (string apikey, string cid, int tid, struct opts)

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

reports/clicks (string apikey, string cid)

The urls tracked and their click counts for a given campaign.

reports/domain-performance (string apikey, string cid)

Get the top 5 performing email domains for this campaign. Users wanting more than 5 should use campaign reports/member-activity() or campaignEmailStatsAIMAll() and generate any additional stats they require.

reports/ecomm-orders (string apikey, string cid, struct opts)

Retrieve the Ecommerce Orders tracked by ecomm/order-add()

reports/eepurl (string apikey, string cid)

Retrieve the eepurl stats from the web/Twitter mentions for this campaign

reports/geo-opens (string apikey, string cid)

Retrieve the countries/regions and number of opens tracked for each. Email address are not returned.

reports/google-analytics (string apikey, string cid)

Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.

reports/member-activity (string apikey, string cid, array emails)

Given a campaign and email address, return the entire click and open history with timestamps, ordered by time. If you need to dump the full activity for a campaign and/or get incremental results, you should use the campaignSubscriberActivity Export API method, not this, especially for large campaigns.

reports/not-opened (string apikey, string cid, struct opts)

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

reports/opened (string apikey, string cid, struct opts)

Retrieve the list of email addresses that opened a given campaign with how many times they opened

reports/sent-to (string apikey, string cid, struct opts)

Get email addresses the campaign was sent to

reports/share (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. Note subsequent calls will overwrite anything already set for the same campign (eg, the password)

reports/summary (string apikey, string cid)

Retrieve relevant aggregate campaign statistics (opens, bounces, clicks, etc.)

reports/unsubscribes (string apikey, string cid, struct opts)

Get all unsubscribed email addresses for a given campaign

Templates Related Methods  

templates/add (string apikey, string name, string html, int folder_id)

Create a new user template, NOT campaign content. These templates can then be applied while creating campaigns.

templates/del (string apikey, int template_id)

Delete (deactivate) a user template

templates/info (string apikey, int template_id, string type)

Pull details for a specific template to help support editing

templates/list (string apikey, struct types, struct filters)

Retrieve various templates available in the system, allowing some thing similar to our template gallery to be created.

templates/undel (string apikey, int template_id)

Undelete (reactivate) a user template

templates/update (string apikey, int template_id, struct values)

Replace the content of a user template, NOT campaign content.

Users Related Methods  

users/invite (string apikey, string email, string role, string msg)

Invite a user to your account

users/invite-resend (string apikey, string email)

Resend an invite a user to your account. Note, if the same address has been invited multiple times, this will simpy re-send the most recent invite

users/invite-revoke (string apikey, string email)

Revoke an invitation sent to a user to your account. Note, if the same address has been invited multiple times, this will simpy revoke the most recent invite

users/invites (string apikey)

Retrieve the list of pending users invitations have been sent for.

users/login-revoke (string apikey, string username)

Revoke access for a specified login

users/logins (string apikey)

Retrieve the list of active logins.

users/profile (string apikey)

Retrieve the profile for the login owning the provided API Key

Vip Related Methods  

vip/activity (string apikey)

Retrieve all Activity (opens/clicks) for VIPs over the past 10 days

vip/add (string apikey, string id, array emails)

Add VIPs (previously called Golden Monkeys)

vip/del (string apikey, string id, array emails)

Remove VIPs - this does not affect list membership

vip/members (string apikey)

Retrieve all Golden Monkey(s) for an account

Goal Related Methods  

goal/events (string apikey, string list_id, struct email, int start, int limit)

Retrieve goal event data for a particular list member. Note: only unique events are returned. If a user triggers a particular event multiple times, you will still only receive one entry for that event.

goal/record-event (string apikey, string list_id, struct email, string campaign_id, string event)

This allows programmatically trigger goal event collection without the use of front-end code.

Conversations Related Methods  

conversations/list (string apikey, string list_id, string leid, string campaign_id, int start, int limit)

Retrieve conversation metadata, includes message data for the most recent message in the conversation

conversations/messages (string apikey, string conversation_id, boolean mark_as_read, int start, int limit)

Retrieve conversation messages

conversations/reply (string apikey, string conversation_id, string message)

Reply to a conversation