> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://mailchimp.com/developer/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mailchimp.com/developer/_mcp/server. # Get lists info GET https://api.mailchimp.com/3.0/lists Get information about all lists in the account. Reference: https://mailchimp.com/developer/marketing/api/lists/list ## Authentication - `Authorization` header (bearer token, required) — Authorization using a Mailchimp API key (a.k.a. Bearer token) - `Authorization` header (bearer token, required) — Authorization using OAuth ## Request ### Query parameters - `fields` (list of string, optional) — A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation. - `exclude_fields` (list of string, optional) — A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation. - `count` (integer, optional, default: 10) — The number of records to return. Default value is 10. Maximum value is 1000 - `offset` (integer, optional, default: 0) — Used for [pagination](https://mailchimp.com/developer/marketing/docs/methods-parameters/#pagination), this is the number of records from a collection to skip. Default value is 0. - `before_date_created` (string, optional) — Restrict response to lists created before the set date. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00. - `since_date_created` (string, optional) — Restrict results to lists created after the set date. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00. - `before_campaign_last_sent` (string, optional) — Restrict results to lists created before the last campaign send date. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00. - `since_campaign_last_sent` (string, optional) — Restrict results to lists created after the last campaign send date. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00. - `email` (string, optional) — Restrict results to lists that include a specific subscriber's email address. - `sort_field` (enum, optional) — Returns files sorted by the specified field. - Allowed values: `date_created` - `sort_dir` (enum, optional) — Determines the order direction for sorted results. - Allowed values: `ASC`, `DESC` - `has_ecommerce_store` (boolean, optional) — Restrict results to lists that contain an active, connected, undeleted ecommerce store. - `include_total_contacts` (boolean, optional, deprecated) — Deprecated. Return the total_contacts field in the stats response, which contains an approximate count of subscribed, unsubscribed, and transactional contacts. For a complete audience contact count, use the /audiences endpoint instead. ## Response ### 200 - `lists` (list of SubscriberList, required) — An array of objects, each representing a list. - `_links` (list of 30ListsGetResponsesContentApplicationJsonSchemaLinksItems, optional) — A list of link types and descriptions for the API schema documents. - `constraints` (30ListsGetResponsesContentApplicationJsonSchemaConstraints, optional) — Do particular authorization constraints around this collection limit creation of new instances? - `total_items` (integer, optional) — The total number of items matching the query regardless of pagination. ## Types ### SubscriberList Information about a specific list. - `_links` (list of SubscriberListLinksItems, optional) — A list of link types and descriptions for the API schema documents. - `beamer_address` (string, optional) — The list's [Email Beamer](https://mailchimp.com/help/use-email-beamer-to-create-a-campaign/) address. - `campaign_defaults` (SubscriberListCampaignDefaults, optional) — [Default values for campaigns](https://mailchimp.com/help/edit-your-emails-subject-preview-text-from-name-or-from-email-address/) created for this list. - `contact` (SubscriberListContact, optional) — [Contact information displayed in campaign footers](https://mailchimp.com/help/about-campaign-footers/) to comply with international spam laws. - `date_created` (datetime, optional) — The date and time that this list was created in ISO 8601 format. - `double_optin` (boolean, optional, default: false) — Whether or not to require the subscriber to confirm subscription via email. - `email_type_option` (boolean, optional) — Whether the list supports [multiple formats for emails](https://mailchimp.com/help/audience-settings-and-defaults/). When set to `true`, subscribers can choose whether they want to receive HTML or plain-text emails. When set to `false`, subscribers will receive HTML emails, with a plain-text alternative backup. - `has_welcome` (boolean, optional, default: false) — Whether or not this list has a welcome automation connected. Welcome Automations: welcomeSeries, singleWelcome, emailFollowup. - `id` (string, optional) — A string that uniquely identifies this list. - `list_rating` (integer, optional) — An auto-generated activity score for the list (0-5). - `marketing_permissions` (boolean, optional, default: false) — Whether or not the list has marketing permissions (eg. GDPR) enabled. - `modules` (list of string, optional) — Any list-specific modules installed for this list. - `name` (string, optional) — The name of the list. - `notify_on_subscribe` (string, optional, default: false) — The email address to send [subscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to. - `notify_on_unsubscribe` (string, optional, default: false) — The email address to send [unsubscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to. - `permission_reminder` (string, optional) — The [permission reminder](https://mailchimp.com/help/edit-the-permission-reminder/) for the list. - `stats` (SubscriberListStats, optional) — Stats for the list. Many of these are cached for at least five minutes. - `subscribe_url_long` (string, optional) — The full version of this list's subscribe form (host will vary). - `subscribe_url_short` (string, optional) — Our [url shortened](https://mailchimp.com/help/share-your-signup-form/) version of this list's subscribe form. - `use_archive_bar` (boolean, optional, default: false) — Whether campaigns for this list use the [Archive Bar](https://mailchimp.com/help/about-email-campaign-archives-and-pages/) in archives by default. - `visibility` (enum, optional) — Legacy - visibility settings are no longer used - Allowed values: `pub`, `prv` - `web_id` (integer, optional) — The ID used in the Mailchimp web application. View this list in your Mailchimp account at `https://{dc}.admin.mailchimp.com/lists/members/?id={web_id}`. ### 30ListsGetResponsesContentApplicationJsonSchemaLinksItems This object represents a link from the resource where it is found to another resource or action that may be performed. - `href` (string, optional) — This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` (enum, optional) — The HTTP method that should be used when accessing the URL defined in 'href'. - Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD` - `rel` (string, optional) — As with an HTML 'rel' attribute, this describes the type of link. - `schema` (string, optional) — For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` (string, optional) — For GETs, this is a URL representing the schema that the response should conform to. ### 30ListsGetResponsesContentApplicationJsonSchemaConstraints Do particular authorization constraints around this collection limit creation of new instances? - `max_instances` (integer, required) — How many total instances of this resource are allowed? This is independent of any filter conditions applied to the query. As a special case, -1 indicates unlimited. - `may_create` (boolean, required) — May the user create additional instances of this resource? - `current_total_instances` (integer, optional) — How many total instances of this resource are already in use? This is independent of any filter conditions applied to the query. Value may be larger than max_instances. As a special case, -1 is returned when access is unlimited. ### SubscriberListLinksItems This object represents a link from the resource where it is found to another resource or action that may be performed. - `href` (string, optional) — This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` (enum, optional) — The HTTP method that should be used when accessing the URL defined in 'href'. - Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD` - `rel` (string, optional) — As with an HTML 'rel' attribute, this describes the type of link. - `schema` (string, optional) — For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to. - `targetSchema` (string, optional) — For GETs, this is a URL representing the schema that the response should conform to. ### SubscriberListCampaignDefaults [Default values for campaigns](https://mailchimp.com/help/edit-your-emails-subject-preview-text-from-name-or-from-email-address/) created for this list. - `from_email` (string, optional) — The default from email for campaigns sent to this list. - `from_name` (string, optional) — The default from name for campaigns sent to this list. - `language` (string, optional) — The default language for this lists's forms. - `subject` (string, optional) — The default subject line for campaigns sent to this list. ### SubscriberListContact [Contact information displayed in campaign footers](https://mailchimp.com/help/about-campaign-footers/) to comply with international spam laws. - `address1` (string, optional) — The street address for the list contact. - `address2` (string, optional) — The street address for the list contact. - `city` (string, optional) — The city for the list contact. - `company` (string, optional) — The company name for the list. - `country` (string, optional) — A two-character ISO3166 country code. Defaults to US if invalid. - `phone` (string, optional) — The phone number for the list contact. - `state` (string, optional) — The state for the list contact. - `zip` (string, optional) — The postal or zip code for the list contact. ### SubscriberListStats Stats for the list. Many of these are cached for at least five minutes. - `avg_sub_rate` (double, optional) — The average number of subscriptions per month for the list (not returned if we haven't calculated it yet). - `avg_unsub_rate` (double, optional) — The average number of unsubscriptions per month for the list (not returned if we haven't calculated it yet). - `campaign_count` (integer, optional) — The number of campaigns in any status that use this list. - `campaign_last_sent` (datetime, optional) — The date and time the last campaign was sent to this list in ISO 8601 format. This is updated when a campaign is sent to 10 or more recipients. - `cleaned_count` (integer, optional) — The number of members cleaned from the list. - `cleaned_count_since_send` (integer, optional) — The number of members cleaned from the list since the last campaign was sent. - `click_rate` (double, optional) — The average click rate (a percentage represented as a number between 0 and 100) per campaign for the list (not returned if we haven't calculated it yet). - `last_sub_date` (datetime, optional) — The date and time of the last time someone subscribed to this list in ISO 8601 format. - `last_unsub_date` (datetime, optional) — The date and time of the last time someone unsubscribed from this list in ISO 8601 format. - `member_count` (integer, optional) — The number of active members in the list. - `member_count_since_send` (integer, optional) — The number of active members in the list since the last campaign was sent. - `merge_field_count` (integer, optional) — The number of merge fields ([audience field](https://mailchimp.com/help/getting-started-with-merge-tags/)) for this list (doesn't include EMAIL). - `open_rate` (double, optional) — The average open rate (a percentage represented as a number between 0 and 100) per campaign for the list (not returned if we haven't calculated it yet). - `target_sub_rate` (double, optional) — The target number of subscriptions per month for the list to keep it growing (not returned if we haven't calculated it yet). - `total_contacts` (integer, optional) — An approximate count of subscribed, unsubscribed, and transactional contacts in the list. Does not include cleaned, archived, pending, or contacts that need to be reconfirmed. Requires the (deprecated) include_total_contacts query parameter to be included; for a complete audience contact count, use the /audiences endpoint instead. - `unsubscribe_count` (integer, optional) — The number of members who have unsubscribed from the list. - `unsubscribe_count_since_send` (integer, optional) — The number of members who have unsubscribed since the last campaign was sent. ## Examples **Response** ```json { "lists": [ { "_links": [ { "href": "string", "method": "GET", "rel": "string", "schema": "string", "targetSchema": "string" } ], "beamer_address": "string", "campaign_defaults": { "from_email": "string", "from_name": "string", "language": "string", "subject": "string" }, "contact": { "address1": "string", "address2": "string", "city": "string", "company": "string", "country": "string", "phone": "string", "state": "string", "zip": "string" }, "date_created": "2024-01-15T09:30:00Z", "double_optin": false, "email_type_option": true, "has_welcome": false, "id": "string", "list_rating": 1, "marketing_permissions": false, "modules": [ "string" ], "name": "string", "notify_on_subscribe": "string", "notify_on_unsubscribe": "string", "permission_reminder": "string", "stats": { "avg_sub_rate": 1.1, "avg_unsub_rate": 1.1, "campaign_count": 1, "campaign_last_sent": "2024-01-15T09:30:00Z", "cleaned_count": 1, "cleaned_count_since_send": 1, "click_rate": 1.1, "last_sub_date": "2024-01-15T09:30:00Z", "last_unsub_date": "2024-01-15T09:30:00Z", "member_count": 1, "member_count_since_send": 1, "merge_field_count": 1, "open_rate": 1.1, "target_sub_rate": 1.1, "total_contacts": 1, "unsubscribe_count": 1, "unsubscribe_count_since_send": 1 }, "subscribe_url_long": "string", "subscribe_url_short": "string", "use_archive_bar": false, "visibility": "pub", "web_id": 1 } ], "_links": [ { "href": "string", "method": "GET", "rel": "string", "schema": "string", "targetSchema": "string" } ], "constraints": { "max_instances": 1, "may_create": true, "current_total_instances": 1 }, "total_items": 1 } ``` **SDK Code** ```python import requests url = "https://api.mailchimp.com/3.0/lists" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.mailchimp.com/3.0/lists'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.mailchimp.com/3.0/lists" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.mailchimp.com/3.0/lists") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.mailchimp.com/3.0/lists") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.mailchimp.com/3.0/lists', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.mailchimp.com/3.0/lists"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.mailchimp.com/3.0/lists")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```