Mailchimp Segments API

swagger: '2.0'
info:
  version: 3.0.55
  title: Mailchimp Marketing Abuse Segments 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: Segments
paths:
  /lists/{list_id}/segments:
    get:
      summary: Mailchimp List Segments
      description: Get information about all available segments for a specific list.
      operationId: previewASegment
      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: list_id
        x-title: List ID
        in: path
        description: The unique ID for the list.
        required: true
        type: string
        example: '500123'
      - name: type
        x-title: Segment Type
        in: query
        required: false
        description: Limit results based on segment type.
        type: string
        example: example_value
      - name: since_created_at
        x-title: Since Created At
        in: query
        description: 'Restrict results to segments created after the set time. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        required: false
        type: string
        example: '2026-01-15T10:30:00Z'
      - name: before_created_at
        x-title: Before Created At
        in: query
        description: 'Restrict results to segments created before the set time. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        required: false
        type: string
        example: '2026-01-15T10:30:00Z'
      - name: include_cleaned
        in: query
        x-title: Include Cleaned
        description: Include cleaned members in response
        required: false
        type: boolean
        x-example: false
        example: example_value
      - name: include_transactional
        in: query
        x-title: Include Transactional
        description: Include transactional members in response
        required: false
        type: boolean
        x-example: false
        example: example_value
      - name: include_unsubscribed
        in: query
        x-title: Include Unsubscribed
        description: Include unsubscribed members in response
        required: false
        type: boolean
        x-example: false
        example: example_value
      - name: since_updated_at
        x-title: Since Updated At
        in: query
        description: 'Restrict results to segments update after the set time. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        required: false
        type: string
        example: '2026-01-15T10:30:00Z'
      - name: before_updated_at
        x-title: Before Updated At
        in: query
        description: 'Restrict results to segments update before the set time. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        required: false
        type: string
        example: '2026-01-15T10:30:00Z'
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Collection of Segments
            description: A list of available segments.
            properties:
              segments:
                type: array
                items:
                  type: object
                  title: List
                  description: Information about a specific segment.
                  properties:
                    id:
                      type: integer
                      title: Segment ID
                      description: The unique id for the segment.
                      readOnly: true
                    name:
                      type: string
                      title: Segment Name
                      description: The name of the segment.
                    member_count:
                      type: integer
                      title: Member Count
                      description: The number of active subscribers currently included in the segment.
                      readOnly: true
                    type:
                      type: string
                      title: Type
                      description: The type of segment. Static segments are now known as tags. Learn more about [tags](https://mailchimp.com/help/getting-started-tags?utm_source=mc-api&utm_medium=docs&utm_campaign=apidocs).
                      readOnly: true
                      enum:
                      - saved
                      - static
                      - fuzzy
                    created_at:
                      type: string
                      title: Date Created
                      description: The date and time the segment was created in ISO 8601 format.
                      readOnly: true
                      format: date-time
                    updated_at:
                      type: string
                      title: Date Updated
                      description: The date and time the segment was last updated in ISO 8601 format.
                      format: date-time
                      readOnly: true
                    options:
                      type: object
                      title: Conditions
                      description: The conditions of the segment. Static segments (tags) and fuzzy segments don't have conditions.
                      properties:
                        match:
                          type: string
                          title: Match
                          description: Match type.
                          enum:
                          - any
                          - all
                        conditions:
                          type: array
                          title: Segment Type
                          description: Segment match conditions. There are multiple possible types, see the [condition types documentation](https://mailchimp.com/developer/marketing/docs/alternative-schemas/#segment-condition-schemas).
                          items:
                            x-discriminator:
                              type: string
                              propertyName: condition_type
                            x-oneOf:
                            - type: object
                              title: Aim Segment
                              description: Segment by interaction with a specific campaign.
                              properties:
                                condition_type:
                                  type: string
                                  x-value: Aim
                                  enum:
                                  - Aim
                                field:
                                  type: string
                                  enum:
                                  - aim
                                  title: Segment Field
                                  description: Segment by interaction with a specific campaign.
                                  example: aim
                                op:
                                  type: string
                                  enum:
                                  - open
                                  - click
                                  - sent
                                  - noopen
                                  - noclick
                                  - nosent
                                  title: Segment Operator
                                  description: 'The status of the member with regard to their campaign interaction. One of the following: opened, clicked, was sent, didn''t open, didn''t click, or was not sent.'
                                  example: open
                                value:
                                  type: string
                                  title: Segment Data
                                  description: Either the web id value for a specific campaign or 'any' to account for subscribers who have/have not interacted with any campaigns.
                                  example: any
                            - type: object
                              title: Automation Segment
                              description: Segment by interaction with an Automation workflow.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: Automation
                                  enum:
                                  - Automation
                                field:
                                  type: string
                                  enum:
                                  - automation
                                  title: Segment Field
                                  description: Segment by interaction with an Automation workflow.
                                  example: automation
                                op:
                                  type: string
                                  enum:
                                  - started
                                  - completed
                                  - not_started
                                  - not_completed
                                  title: Segment Operator
                                  description: 'The status of the member with regard to the automation workflow. One of the following: has started the workflow, has completed the workflow, has not started the workflow, or has not completed the workflow.'
                                  example: started
                                value:
                                  type: string
                                  title: Segment Data
                                  description: The web id for the automation workflow to segment against.
                                  example: '2135217'
                            - type: object
                              title: Poll Activity Segment
                              description: Segment by poll activity.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: CampaignPoll
                                  enum:
                                  - CampaignPoll
                                field:
                                  type: string
                                  enum:
                                  - poll
                                  title: Segment Field
                                  description: Segment by poll activity.
                                  example: poll
                                op:
                                  type: string
                                  enum:
                                  - member
                                  - notmember
                                  title: Segment Operator
                                  description: Members have/have not interacted with a specific poll in a Mailchimp email.
                                  example: member
                                value:
                                  type: number
                                  title: Segment Operator
                                  description: The id for the poll.
                                  example: 409
                            - type: object
                              title: Conversation Segment
                              description: Segment by interaction with a campaign via Conversations.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: Conversation
                                  enum:
                                  - Conversation
                                field:
                                  type: string
                                  enum:
                                  - conversation
                                  title: Segment Field
                                  description: Segment by interaction with a campaign via Conversations.
                                  example: conversation
                                op:
                                  type: string
                                  enum:
                                  - member
                                  - notmember
                                  title: Segment Operator
                                  description: 'The status of a member''s interaction with a conversation. One of the following: has replied or has not replied.'
                                  example: member
                                value:
                                  type: string
                                  title: Segment Data
                                  description: The web id value for a specific campaign or 'any' to account for subscribers who have/have not interacted with any campaigns.
                                  example: any
                            - type: object
                              title: Date Segment
                              description: Segment by a specific date field.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: Date
                                  enum:
                                  - Date
                                field:
                                  type: string
                                  enum:
                                  - timestamp_opt
                                  - info_changed
                                  - ecomm_date
                                  title: Segment Field
                                  description: 'The type of date field to segment on: The opt-in time for a signup, the date the subscriber was last updated, or the date of their last ecomm purchase.'
                                  example: timestamp_opt
                                op:
                                  type: string
                                  enum:
                                  - greater
                                  - less
                                  - is
                                  - not
                                  - blank
                                  - blank_not
                                  - within
                                  - notwithin
                                  title: Segment Operator
                                  description: 'When the event took place:  Before, after, is a specific date, is not a specific date, is blank, or is not blank.'
                                  example: greater
                                value:
                                  type: string
                                  title: Segment Data
                                  description: 'What type of data to segment on: a specific date, a specific campaign, or the last campaign sent.'
                                  example: date
                                extra:
                                  type: string
                                  title: Segment Extra Value
                                  description: When segmenting on 'date' or 'campaign', the date for the segment formatted as YYYY-MM-DD or the web id for the campaign.
                                  example: '2015-01-30'
                            - type: object
                              title: Email Client Segment
                              description: Segment by use of a particular email client.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: EmailClient
                                  enum:
                                  - EmailClient
                                field:
                                  type: string
                                  enum:
                                  - email_client
                                  title: Segment Field
                                  description: Segment by use of a particular email client.
                                  example: email_client
                                op:
                                  type: string
                                  enum:
                                  - client_is
                                  - client_not
                                  title: Segment Operator
                                  description: The operation to determine whether we select clients that match the value, or clients that do not match the value.
                                  example: client_is
                                value:
                                  type: string
                                  title: Segment Data
                                  description: The name of the email client.
                                  example: Gmail
                            - type: object
                              title: Language Segment
                              description: Segment by language.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: Language
                                  enum:
                                  - Language
                                field:
                                  type: string
                                  enum:
                                  - language
                                  title: Segment Field
                                  description: Segmenting based off of a subscriber's language.
                                  example: language
                                op:
                                  type: string
                                  enum:
                                  - is
                                  - not
                                  title: Segment Operator
                                  description: Whether the member's language is or is not set to a specific language.
                                  example: is
                                value:
                                  type: string
                                  title: Segment Data
                                  description: A two-letter language identifier.
                                  example: en
                            - type: object
                              title: Member Rating Segment
                              description: Segment by member rating.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: MemberRating
                                  enum:
                                  - MemberRating
                                field:
                                  type: string
                                  enum:
                                  - rating
                                  title: Segment Field
                                  description: Segment by member rating.
                                  example: rating
                                op:
                                  type: string
                                  enum:
                                  - is
                                  - not
                                  - greater
                                  - less
                                  title: Segment Operator
                                  description: Members who have have a rating that is/not exactly a given number or members who have a rating greater/less than a given number.
                                  example: greater
                                value:
                                  type: number
                                  title: Segment Operator
                                  description: The star rating number to segment against.
                                  example: 4
                            - type: object
                              title: Signup Source Segment
                              description: Segment by signup source.
                              required:
                              - field
                              - condition_type
                              - op
                              properties:
                                condition_type:
                                  type: string
                                  enum:
                                  - SignupSource
                                  x-value: SignupSource
                                  title: Type
                                field:
                                  type: string
                                  enum:
                                  - source
                                  title: Segment Field
                                  example: source
                                op:
                                  type: string
                                  enum:
                                  - source_is
                                  - source_not
                                  title: Segment Operator
                                  description: Whether the member's signup source was/was not a particular value.
                                  example: source_is
                                value:
                                  type: string
                                  title: Segment Data
                                  description: The signup source.
                                  example: List Import
                            - type: object
                              title: Survey Monkey Segment
                              description: Segment by interaction with a SurveyMonkey survey.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: SurveyMonkey
                                  enum:
                                  - SurveyMonkey
                                field:
                                  type: string
                                  enum:
                                  - survey_monkey
                                  title: Segment Field
                                  description: Segment by interaction with a SurveyMonkey survey.
                                  example: survey_monkey
                                op:
                                  type: string
                                  enum:
                                  - started
                                  - completed
                                  - not_started
                                  - not_completed
                                  title: Segment Operator
                                  description: 'The status of the member with regard to the survey.One of the following: has started the survey, has completed the survey, has not started the survey, or has not completed the survey.'
                                  example: started
                                value:
                                  type: string
                                  title: Survey ID
                                  description: The unique ID of the survey monkey survey.
                                  example: '32179586'
                            - type: object
                              title: VIP Segment
                              description: Segment by VIP status.
                              required:
                              - field
                              - op
                              properties:
                                condition_type:
                                  type: string
                                  x-value: VIP
                                  enum:
                                  - VIP
                                field:
                                  type: string
                                  enum:
                                  - gmonkey
                                  title: Segment Field
                                  description: Segment by VIP status.
                                  example: gmonkey
                                op:
                                  type: string
                                  enum:
                                  - member
                                  - notmember
                                  title: Segment Operator
                                  description: Whether the member is or is not marked as VIP.
                                  example: member
                            - type: object
                              title: Interests Segment
                              description: Segment by an interest group merge field.
                              properties:
                                condition_type:
                                  type: string
                                  x-value: Interests
                                  enum:
                                  - Interests
                                field:
                                  type: string
                                  title: Segment Field
                                  description: Segmenting based on interest group information. This should start with 'interests-' followed by the grouping id. Ex. 'interests-123'.
                                  example: interests-123
                                op:
                                  type: string
                                  enum:
                                  - interestcontains
                                  - interestcontainsall
                                  - interestnotcontains
                                  title: Segment Operator
                                  description: Whether the member is a part of one, all, or none of the groups.
                                  example: interestcontains
                                value:
                                  type: array
                                  title: Segment Value
                                  description: An array containing strings, each representing a group id.
                                  items:
                                    type: string
                                    example:
                                    - '44401'
                                    - '44405'
                                    - '44409'
                            - type: object
                              title: Ecommerce Category Segment
                              description: Segment by purchases in specific items or categories.
                              properties:
                                condition_type:
                                  type: string
                                  x-value: EcommCategory
                                  enum:
                                  - EcommCategory
                                field:
                                  type: string
                                  enum:
                                  - ecomm_cat
                                  - ecomm_prod
                                  title: Segment Field
                                  description: Segment by purchases in specific items or categories.
                                  example: ecomm_cat
                                op:
                                  type: string
                                  enum:
                                  - is
                                  - not
                                  - contains
                                  - notcontain
                                  - starts
                                  - ends
                                  title: Segment Operator
                                  description: A member who has purchased from a category/specific item that is/is not a specific name, where the category/item name contains/doesn't contain a specific phrase or string, or a category/item name that starts/ends with a string.
                                  example: is
                                value:
                                  type: string
                                  title: Segment Data
                                  description: The ecommerce category/item information.
                                  example: Product
                            - type: object
                              title: Ecommerce Number Segment
                              description: Segment by average spent total, number of orders, total number of products purchased, or average number of products per order.
                              required:
                              - field
                              - op
                              - value
                              properties:
                                condition_type:
                                  type: string
                                  x-value: EcommNumber
                                  enum:
                                  - EcommNumber
                                field:
                                  type: string
                                  enum:
                                  - ecomm_spent_avg
                                  - ecomm_orders
                                  - ecomm_prod_all
                             

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