Mailchimp Lists API

swagger: '2.0'
info:
  version: 3.0.55
  title: Mailchimp Marketing Abuse 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
  description: '

    The Mailchimp Marketing API provides programmatic access to Mailchimp data

    and functionality, allowing developers to build custom features to do

    things like sync email activity and campaign analytics with their

    database, manage audiences and campaigns, and more.'
host: server.api.mailchimp.com
basePath: /3.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
- application/problem+json
security:
- basicAuth: []
tags:
- name: Lists
paths:
  /lists:
    get:
      summary: Mailchimp 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
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - 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
        type: array
        collectionFormat: csv
        items:
          type: string
        example: example_value
      - name: count
        x-title: Count
        in: query
        description: The number of records to return. Default value is 10. Maximum value is 1000
        required: false
        default: 10
        maximum: 1000
        type: integer
        example: example_value
      - name: offset
        x-title: Offset
        in: query
        description: Used for [pagination](https://mailchimp.com/developer/marketing/docs/methods-parameters/#pagination), this it the number of records from a collection to skip. Default value is 0.
        required: false
        default: 0
        type: integer
        example: example_value
      - 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.'
        type: string
        example: example_value
      - 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.'
        type: string
        example: example_value
      - 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.'
        type: string
        example: example_value
      - 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.'
        type: string
        example: example_value
      - name: email
        x-title: Subscriber Email
        description: Restrict results to lists that include a specific subscriber's email address.
        in: query
        required: false
        type: string
        example: user@example.com
      - name: sort_field
        x-title: Sort By Field
        description: Returns files sorted by the specified field.
        in: query
        required: false
        type: string
        enum:
        - date_created
        example: example_value
      - name: sort_dir
        x-title: Sort Direction
        description: Determines the order direction for sorted results.
        in: query
        required: false
        type: string
        enum:
        - ASC
        - DESC
        example: example_value
      - 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.
        type: boolean
        example: example_value
      - name: include_total_contacts
        x-title: Include Total Contacts
        in: query
        description: Return the total_contacts field in the stats response, which contains an approximate count of all contacts in any state.
        required: false
        type: boolean
        example: example_value
      responses:
        '200':
          description: ''
          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/change-audience-name-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: The number of contacts in the list, including subscribed, unsubscribed, pending, cleaned, deleted, transactional, and those that need to be reconfirmed. Requires include_total_contacts query parameter to be included.
                          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
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Lists
      x-custom-config:
        methodNameSnake: get_all_lists
        methodNameCamel: getAllLists
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Mailchimp Add List
      description: Create a new list in your Mailchimp account.
      operationId: postLists
      parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          title: Subscriber List
          description: Information about a specific list.
          required:
          - name
          - permission_reminder
          - email_type_option
          - contact
          - campaign_defaults
          properties:
            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.'
              required:
              - company
              - address1
              - city
              - country
              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.'
              required:
              - from_name
              - from_email
              - subject
              - language
              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
            email_type_option:
              type: boolean
              title: Email Type Option
              description: Whether the list supports [multiple formats for emails](https://mailchimp.com/help/change-audience-name-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 altern

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