--- title: "Get lists info" method: GET path: "/3.0/lists" tags: ["lists"] --- # Get lists info `GET /3.0/lists` ## Request - Base URL: `https://api.mailchimp.com` - URL: `https://api.mailchimp.com/3.0/lists` - Auth: one of: - HTTP bearer - OAuth 2 - Authorization code: `https://login.mailchimp.com/oauth2/authorize` - Token URL: `https://login.mailchimp.com/oauth2/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Get information about all lists in the account. ## Query parameters - `fields` string[] - `exclude_fields` string[] - `count` integer - `offset` integer - `before_date_created` string - `since_date_created` string - `before_campaign_last_sent` string - `since_campaign_last_sent` string - `email` string - `sort_field` 'date_created' - `sort_dir` 'ASC' | 'DESC' - `has_ecommerce_store` boolean - `include_total_contacts` boolean ## Response `200` - object: A collection of subscriber lists for this account. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: 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: For GETs, this is a URL representing the schema that the response should conform to. - `constraints` object: Do particular authorization constraints around this collection limit creation of new instances? - `current_total_instances` integer: 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. - `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? - `lists` object[], required: An array of objects, each representing a list. - `_links` object[]: A list of link types and descriptions for the API schema documents. - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action. - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'. - `rel` string: As with an HTML 'rel' attribute, this describes the type of link. - `schema` string: 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: For GETs, this is a URL representing the schema that the response should conform to. - `beamer_address` string: The list's [Email Beamer](https://mailchimp.com/help/use-email-beamer-to-create-a-campaign/) address. - `campaign_defaults` object: [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: The default from email for campaigns sent to this list. - `from_name` string: The default from name for campaigns sent to this list. - `language` string: The default language for this lists's forms. - `subject` string: The default subject line for campaigns sent to this list. - `contact` object: [Contact information displayed in campaign footers](https://mailchimp.com/help/about-campaign-footers/) to comply with international spam laws. - `address1` string: The street address for the list contact. - `address2` string: The street address for the list contact. - `city` string: The city for the list contact. - `company` string: The company name for the list. - `country` string: A two-character ISO3166 country code. Defaults to US if invalid. - `phone` string: The phone number for the list contact. - `state` string: The state for the list contact. - `zip` string: The postal or zip code for the list contact. - `date_created` string, date-time: The date and time that this list was created in ISO 8601 format. - `double_optin` boolean: Whether or not to require the subscriber to confirm subscription via email. - `email_type_option` boolean: 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: Whether or not this list has a welcome automation connected. Welcome Automations: welcomeSeries, singleWelcome, emailFollowup. - `id` string: A string that uniquely identifies this list. - `list_rating` integer: An auto-generated activity score for the list (0-5). - `marketing_permissions` boolean: Whether or not the list has marketing permissions (eg. GDPR) enabled. - `modules` string[]: Any list-specific modules installed for this list. - `name` string: The name of the list. - `notify_on_subscribe` string: The email address to send [subscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to. - `notify_on_unsubscribe` string: The email address to send [unsubscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to. - `permission_reminder` string: The [permission reminder](https://mailchimp.com/help/edit-the-permission-reminder/) for the list. - `stats` object: Stats for the list. Many of these are cached for at least five minutes. - `avg_sub_rate` number: The average number of subscriptions per month for the list (not returned if we haven't calculated it yet). - `avg_unsub_rate` number: The average number of unsubscriptions per month for the list (not returned if we haven't calculated it yet). - `campaign_count` integer: The number of campaigns in any status that use this list. - `campaign_last_sent` string, date-time: 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: The number of members cleaned from the list. - `cleaned_count_since_send` integer: The number of members cleaned from the list since the last campaign was sent. - `click_rate` number: 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` string, date-time: The date and time of the last time someone subscribed to this list in ISO 8601 format. - `last_unsub_date` string, date-time: The date and time of the last time someone unsubscribed from this list in ISO 8601 format. - `member_count` integer: The number of active members in the list. - `member_count_since_send` integer: The number of active members in the list since the last campaign was sent. - `merge_field_count` integer: 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` number: 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` number: 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: 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: The number of members who have unsubscribed from the list. - `unsubscribe_count_since_send` integer: The number of members who have unsubscribed since the last campaign was sent. - `subscribe_url_long` string: The full version of this list's subscribe form (host will vary). - `subscribe_url_short` string: Our [url shortened](https://mailchimp.com/help/share-your-signup-form/) version of this list's subscribe form. - `use_archive_bar` boolean: Whether campaigns for this list use the [Archive Bar](https://mailchimp.com/help/about-email-campaign-archives-and-pages/) in archives by default. - `visibility` 'pub' | 'prv': Legacy - visibility settings are no longer used - `web_id` integer: 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}`. - `total_items` integer: The total number of items matching the query regardless of pagination. ## Other responses - `default`: An error generated by the Mailchimp API. --- [API](https://skmtc.dev/mailchimp/apis/mailchimp-api.md) - [All operations](https://skmtc.dev/mailchimp/apis/mailchimp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mailchimp/apis/mailchimp-api/revisions/53bf4b156855?raw)