Mailchimp Lists API

openapi: 3.2.0
info:
  version: 3.0.91
  title: Mailchimp Marketing Lists API
  contact:
    name: Mailchimp API Support
    email: apihelp@mailchimp.com
  x-permalink: https://github.com/mailchimp/mailchimp-client-lib-codegen/blob/main/spec/marketing.json
servers:
- url: https://server.api.mailchimp.com/3.0
security:
- basicAuth: []
tags:
- name: lists
paths:
  /lists:
    get:
      summary: Get lists info
      description: Get information about all lists in the account.
      operationId: getLists
      parameters:
      - name: fields
        x-title: Fields
        in: query
        description: A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: exclude_fields
        x-title: Exclude Fields
        in: query
        description: A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: count
        x-title: Count
        in: query
        description: The number of records to return. Default value is 10. Maximum value is 1000
        required: false
        schema:
          type: integer
          default: 10
          maximum: 1000
      - name: offset
        x-title: Offset
        in: query
        description: 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.
        required: false
        schema:
          type: integer
          default: 0
      - name: before_date_created
        x-title: Before Date Created
        in: query
        required: false
        description: 'Restrict response to lists created before the set date. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        schema:
          type: string
      - name: since_date_created
        x-title: Since Date Created
        in: query
        required: false
        description: 'Restrict results to lists created after the set date. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        schema:
          type: string
      - name: before_campaign_last_sent
        x-title: Before Campaign Last Sent
        in: query
        required: false
        description: 'Restrict results to lists created before the last campaign send date. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        schema:
          type: string
      - name: since_campaign_last_sent
        x-title: Since Campaign Last Sent
        in: query
        required: false
        description: 'Restrict results to lists created after the last campaign send date. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        schema:
          type: string
      - name: email
        x-title: Subscriber Email
        description: Restrict results to lists that include a specific subscriber's email address.
        in: query
        required: false
        schema:
          type: string
      - name: sort_field
        x-title: Sort By Field
        description: Returns files sorted by the specified field.
        in: query
        required: false
        schema:
          type: string
          enum:
          - date_created
      - name: sort_dir
        x-title: Sort Direction
        description: Determines the order direction for sorted results.
        in: query
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
      - name: has_ecommerce_store
        x-title: Has Ecommerce Store
        in: query
        required: false
        description: Restrict results to lists that contain an active, connected, undeleted ecommerce store.
        schema:
          type: boolean
      - name: include_total_contacts
        x-title: Include Total Contacts
        in: query
        description: 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.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                title: Subscriber Lists
                description: A collection of subscriber lists for this account. Lists contain subscribers who have opted-in to receive correspondence from you or your organization.
                properties:
                  lists:
                    type: array
                    items:
                      type: object
                      title: Subscriber List
                      description: Information about a specific list.
                      properties:
                        id:
                          type: string
                          title: List ID
                          description: A string that uniquely identifies this list.
                          readOnly: true
                        web_id:
                          type: integer
                          title: List Web ID
                          description: 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}`.
                          readOnly: true
                        name:
                          type: string
                          title: List Name
                          description: The name of the list.
                        contact:
                          type: object
                          title: List Contact
                          description: '[Contact information displayed in campaign footers](https://mailchimp.com/help/about-campaign-footers/) to comply with international spam laws.'
                          properties:
                            company:
                              type: string
                              title: Company Name
                              description: The company name for the list.
                            address1:
                              type: string
                              title: Address
                              description: The street address for the list contact.
                            address2:
                              type: string
                              title: Address
                              description: The street address for the list contact.
                            city:
                              type: string
                              title: City
                              description: The city for the list contact.
                            state:
                              type: string
                              title: State
                              description: The state for the list contact.
                            zip:
                              type: string
                              title: Postal Code
                              description: The postal or zip code for the list contact.
                            country:
                              type: string
                              title: Country Code
                              description: A two-character ISO3166 country code. Defaults to US if invalid.
                            phone:
                              type: string
                              title: Phone Number
                              description: The phone number for the list contact.
                        permission_reminder:
                          type: string
                          title: Permission Reminder
                          description: The [permission reminder](https://mailchimp.com/help/edit-the-permission-reminder/) for the list.
                        use_archive_bar:
                          type: boolean
                          title: Use Archive Bar
                          description: Whether campaigns for this list use the [Archive Bar](https://mailchimp.com/help/about-email-campaign-archives-and-pages/) in archives by default.
                          default: false
                        campaign_defaults:
                          type: object
                          title: Campaign Defaults
                          description: '[Default values for campaigns](https://mailchimp.com/help/edit-your-emails-subject-preview-text-from-name-or-from-email-address/) created for this list.'
                          properties:
                            from_name:
                              type: string
                              title: Sender's Name
                              description: The default from name for campaigns sent to this list.
                            from_email:
                              type: string
                              title: Sender's Email Address
                              description: The default from email for campaigns sent to this list.
                            subject:
                              type: string
                              title: Subject
                              description: The default subject line for campaigns sent to this list.
                            language:
                              type: string
                              title: Language
                              description: The default language for this lists's forms.
                        notify_on_subscribe:
                          type: string
                          title: Notify on Subscribe
                          description: The email address to send [subscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to.
                          default: false
                        notify_on_unsubscribe:
                          type: string
                          title: Notify on Unsubscribe
                          description: The email address to send [unsubscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to.
                          default: false
                        date_created:
                          type: string
                          title: Creation Date
                          description: The date and time that this list was created in ISO 8601 format.
                          format: date-time
                          readOnly: true
                        list_rating:
                          type: integer
                          title: List Rating
                          description: An auto-generated activity score for the list (0-5).
                          readOnly: true
                        email_type_option:
                          type: boolean
                          title: Email Type Option
                          description: 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.
                        subscribe_url_short:
                          type: string
                          title: Subscribe URL Short
                          description: Our [url shortened](https://mailchimp.com/help/share-your-signup-form/) version of this list's subscribe form.
                          readOnly: true
                        subscribe_url_long:
                          type: string
                          title: Subscribe URL Long
                          description: The full version of this list's subscribe form (host will vary).
                          readOnly: true
                        beamer_address:
                          type: string
                          title: Beamer Address
                          description: The list's [Email Beamer](https://mailchimp.com/help/use-email-beamer-to-create-a-campaign/) address.
                          readOnly: true
                        visibility:
                          type: string
                          title: Visibility
                          enum:
                          - pub
                          - prv
                          description: Legacy - visibility settings are no longer used
                        double_optin:
                          type: boolean
                          title: Double Opt In
                          description: Whether or not to require the subscriber to confirm subscription via email.
                          default: false
                        has_welcome:
                          type: boolean
                          title: Has Welcome
                          description: 'Whether or not this list has a welcome automation connected. Welcome Automations: welcomeSeries, singleWelcome, emailFollowup.'
                          default: false
                          example: false
                        marketing_permissions:
                          type: boolean
                          title: Marketing Permissions
                          description: Whether or not the list has marketing permissions (eg. GDPR) enabled.
                          default: false
                        modules:
                          type: array
                          title: Modules
                          description: Any list-specific modules installed for this list.
                          items:
                            type: string
                          readOnly: true
                        stats:
                          type: object
                          title: Statistics
                          description: Stats for the list. Many of these are cached for at least five minutes.
                          readOnly: true
                          properties:
                            member_count:
                              type: integer
                              title: Member Count
                              description: The number of active members in the list.
                              readOnly: true
                            total_contacts:
                              type: integer
                              title: Total Contacts
                              description: 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.
                              readOnly: true
                            unsubscribe_count:
                              type: integer
                              title: Unsubscribe Count
                              description: The number of members who have unsubscribed from the list.
                              readOnly: true
                            cleaned_count:
                              type: integer
                              title: Cleaned Count
                              description: The number of members cleaned from the list.
                              readOnly: true
                            member_count_since_send:
                              type: integer
                              title: Member Count Since Send
                              description: The number of active members in the list since the last campaign was sent.
                              readOnly: true
                            unsubscribe_count_since_send:
                              type: integer
                              title: Unsubscribe Count Since Send
                              description: The number of members who have unsubscribed since the last campaign was sent.
                              readOnly: true
                            cleaned_count_since_send:
                              type: integer
                              title: Cleaned Count Since Send
                              description: The number of members cleaned from the list since the last campaign was sent.
                              readOnly: true
                            campaign_count:
                              type: integer
                              title: Campaign Count
                              description: The number of campaigns in any status that use this list.
                              readOnly: true
                            campaign_last_sent:
                              type: string
                              format: date-time
                              title: Campaign Last Sent
                              description: 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.
                              readOnly: true
                            merge_field_count:
                              type: integer
                              title: Merge Field Count
                              description: The number of merge fields ([audience field](https://mailchimp.com/help/getting-started-with-merge-tags/)) for this list (doesn't include EMAIL).
                              readOnly: true
                            avg_sub_rate:
                              type: number
                              title: Average Subscription Rate
                              description: The average number of subscriptions per month for the list (not returned if we haven't calculated it yet).
                              readOnly: true
                            avg_unsub_rate:
                              type: number
                              title: Average Unsubscription Rate
                              description: The average number of unsubscriptions per month for the list (not returned if we haven't calculated it yet).
                              readOnly: true
                            target_sub_rate:
                              type: number
                              title: Average Subscription Rate
                              description: The target number of subscriptions per month for the list to keep it growing (not returned if we haven't calculated it yet).
                              readOnly: true
                            open_rate:
                              type: number
                              title: Open Rate
                              description: 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).
                              readOnly: true
                            click_rate:
                              type: number
                              title: Click Rate
                              description: 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).
                              readOnly: true
                            last_sub_date:
                              type: string
                              format: date-time
                              title: Date of Last List Subscribe
                              description: The date and time of the last time someone subscribed to this list in ISO 8601 format.
                              readOnly: true
                            last_unsub_date:
                              type: string
                              format: date-time
                              title: Date of Last List Unsubscribe
                              description: The date and time of the last time someone unsubscribed from this list in ISO 8601 format.
                              readOnly: true
                        _links:
                          title: Links
                          description: A list of link types and descriptions for the API schema documents.
                          type: array
                          items:
                            type: object
                            title: Resource Link
                            description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                            properties:
                              rel:
                                type: string
                                title: Rel
                                description: As with an HTML 'rel' attribute, this describes the type of link.
                                readOnly: true
                              href:
                                type: string
                                title: Href
                                description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                                readOnly: true
                              method:
                                type: string
                                title: Method
                                description: The HTTP method that should be used when accessing the URL defined in 'href'.
                                enum:
                                - GET
                                - POST
                                - PUT
                                - PATCH
                                - DELETE
                                - OPTIONS
                                - HEAD
                                readOnly: true
                              targetSchema:
                                type: string
                                title: Target Schema
                                description: For GETs, this is a URL representing the schema that the response should conform to.
                                readOnly: true
                              schema:
                                type: string
                                title: Schema
                                description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                                readOnly: true
                          readOnly: true
                    title: Lists
                    description: An array of objects, each representing a list.
                  total_items:
                    type: integer
                    title: Item Count
                    description: The total number of items matching the query regardless of pagination.
                    readOnly: true
                  constraints:
                    type: object
                    title: Collection Authorization
                    description: Do particular authorization constraints around this collection limit creation of new instances?
                    properties:
                      may_create:
                        type: boolean
                        title: Resource creation authorization
                        description: May the user create additional instances of this resource?
                      max_instances:
                        type: integer
                        title: Max instances
                        description: 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.
                      current_total_instances:
                        type: integer
                        title: Current total instances
                        description: 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.
                    required:
                    - may_create
                    - max_instances
                  _links:
                    title: Links
                    description: A list of link types and descriptions for the API schema documents.
                    type: array
                    items:
                      type: object
                      title: Resource Link
                      description: This object represents a link from the resource where it is found to another resource or action that may be performed.
                      properties:
                        rel:
                          type: string
                          title: Rel
                          description: As with an HTML 'rel' attribute, this describes the type of link.
                          readOnly: true
                        href:
                          type: string
                          title: Href
                          description: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
                          readOnly: true
                        method:
                          type: string
                          title: Method
                          description: The HTTP method that should be used when accessing the URL defined in 'href'.
                          enum:
                          - GET
                          - POST
                          - PUT
                          - PATCH
                          - DELETE
                          - OPTIONS
                          - HEAD
                          readOnly: true
                        targetSchema:
                          type: string
                          title: Target Schema
                          description: For GETs, this is a URL representing the schema that the response should conform to.
                          readOnly: true
                        schema:
                          type: string
                          title: Schema
                          description: For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
                          readOnly: true
                    readOnly: true
                required:
                - lists
            application/problem+json:
              schema:
                type: object
                title: Subscriber Lists
                description: A collection of subscriber lists for this account. Lists contain subscribers who have opted-in to receive correspondence from you or your organization.
                properties:
                  lists:
                    type: array
                    items:
                      type: object
                      title: Subscriber List
                      description: Information about a specific list.
                      properties:
                        id:
                          type: string
                          title: List ID
                          description: A string that uniquely identifies this list.
                          readOnly: true
                        web_id:
                          type: integer
                          title: List Web ID
                          description: 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}`.
                          readOnly: true
                        name:
                          type: string
                          title: List Name
                          description: The name of the list.
                        contact:
                          type: object
                          title: List Contact
                          description: '[Contact information displayed in campaign footers](https://mailchimp.com/help/about-campaign-footers/) to comply with international spam laws.'
                          properties:
                            company:
                              type: string
                              title: Company Name
                              description: The company name for the list.
                            address1:
                              type: string
                              title: Address
                              description: The street address for the list contact.
                            address2:
                              type: string
                              title: Address
                              description: The street address for the list contact.
                            city:
                              type: string
                              title: City
                              description: The city for the list contact.
                            state:
                              type: string
                              title: State
                              description: The state for the list contact.
                            zip:
                              type: string
                              title: Postal Code
                              description: The postal or zip code for the list contact.
                            country:
                              type: string
                              title: Country Code
                              description: A two-character ISO3166 country code. Defaults to US if invalid.
                            phone:
                              type: string
                              title: Phone Number
                              description: The phone number for the list contact.
                        permission_reminder:
                          type: string
                          title: Permission Reminder
                          description: The [permission reminder](https://mailchimp.com/help/edit-the-permission-reminder/) for the list.
                        use_archive_bar:
                          type: boolean
                          title: Use Archive Bar
                          description: Whether campaigns for this list use the [Archive Bar](https://mailchimp.com/help/about-email-campaign-archives-and-pages/) in archives by default.
                          default: false
                        campaign_defaults:
                          type: object
                          title: Campaign Defaults
                          description: '[Default values for campaigns](https://mailchimp.com/help/edit-your-emails-subject-preview-text-from-name-or-from-email-address/) created for this list.'
                          properties:
                            from_name:
                              type: string
                              title: Sender's Name
                              description: The default from name for campaigns sent to this list.
                            from_email:
                              type: string
                              title: Sender's Email Address
                              description: The default from email for campaigns sent to this list.
                            subject:
                              type: string
                              title: Subject
                              description: The default subject line for campaigns sent to this list.
                            language:
                              type: string
                              title: Language
                              description: The default language for this lists's forms.
                        notify_on_subscribe:
                          type: string
                          title: Notify on Subscribe
                          description: The email address to send [subscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to.
                          default: false
                        notify_on_unsubscribe:
                          type: string
                          title: Notify on Unsubscribe
                          description: The email address to send [unsubscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to.
                          def

# --- truncated at 32 KB (2226 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mailchimp/refs/heads/main/openapi/mailchimp-lists-api-openapi.yml