Mailchimp Reporting API

openapi: 3.2.0
info:
  version: 3.0.91
  title: Mailchimp Marketing Reporting 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: reporting
paths:
  /reporting/facebook-ads:
    get:
      description: Get reports of Facebook ads.
      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: sort_field
        x-title: Sort By Field
        description: Returns files sorted by the specified field.
        in: query
        required: false
        schema:
          type: string
          enum:
          - created_at
          - updated_at
          - end_time
      - 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
      responses:
        '200':
          description: List of Facebook Ad Report Instances
          content:
            application/json:
              schema:
                type: object
                description: A collection of Facebook ads.
                properties:
                  facebook_ads:
                    type: array
                    items:
                      allOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            title: ID
                            description: Unique ID of an Outreach.
                          web_id:
                            type: integer
                            title: Web ID
                            description: The ID used in the Mailchimp web application. For example, for a `regular` outreach, you can view this campaign in your Mailchimp account at `https://{dc}.admin.mailchimp.com/campaigns/show/?id={web_id}`.
                          name:
                            type: string
                            title: Name
                            description: Title or name of an Outreach.
                          type:
                            type: string
                            title: Outreach Type
                            description: The type of outreach this object is.
                            enum:
                            - regular
                            - email-touchpoint
                            - plaintext
                            - rss
                            - reconfirm
                            - variate
                            - absplit
                            - automation
                            - facebook
                            - google
                            - autoresponder
                            - transactional
                            - page
                            - website
                            - social_post
                            - survey
                            - customer_journey
                            - sms
                          status:
                            type: string
                            title: Outreach Status
                            description: The status of this outreach.
                            enum:
                            - save
                            - paused
                            - schedule
                            - scheduled
                            - sending
                            - sent
                            - canceled
                            - canceling
                            - active
                            - disconnected
                            - somepaused
                            - draft
                            - completed
                            - partialRejected
                            - pending
                            - rejected
                            - published
                            - unpublished
                          show_report:
                            type: boolean
                            title: Show Report
                            description: 'Outreach report availability. Note: This property is hotly debated in what it _should_ convey. See [MCP-1371](https://jira.mailchimp.com/browse/MCP-1371) for more context.'
                          create_time:
                            type: string
                            title: Create Time
                            format: date-time
                            description: The date and time the outreach was created in ISO 8601 format.
                          start_time:
                            type: string
                            title: Start Time
                            format: date-time
                            description: The date and time the outreach was started in ISO 8601 format.
                          updated_at:
                            type: string
                            title: Updated At
                            format: date-time
                            description: The date and time the outreach was last updated in ISO 8601 format.
                          canceled_at:
                            type: string
                            title: Canceled At
                            format: date-time
                            description: The date and time the outreach was canceled in ISO 8601 format.
                          published_time:
                            type: string
                            title: Publish Time
                            format: date-time
                            description: The date and time the outreach was (or will be) published in ISO 8601 format.
                          has_segment:
                            type: boolean
                            title: Has Segment
                            description: If this outreach targets a segment of your audience.
                          report_summary:
                            type: object
                            title: Report Summary
                            description: High level reporting stats for an outreach.
                            properties:
                              opens:
                                type: integer
                              proxy_excluded_opens:
                                type: integer
                              unique_opens:
                                type: integer
                              proxy_excluded_unique_opens:
                                type: integer
                              open_rate:
                                type: number
                              proxy_excluded_open_rate:
                                type: number
                              clicks:
                                type: integer
                              subscriber_clicks:
                                type: integer
                              click_rate:
                                type: number
                              visits:
                                type: integer
                              unique_visits:
                                type: integer
                              conversion_rate:
                                type: number
                              subscribes:
                                type: integer
                              ecommerce:
                                type: object
                                properties:
                                  total_revenue:
                                    type: number
                                  currency_code:
                                    type: string
                                  average_order_revenue:
                                    type: number
                              impressions:
                                type: number
                              reach:
                                type: integer
                              engagements:
                                type: integer
                              total_sent:
                                type: integer
                          recipients:
                            type: object
                            title: Recipients
                            description: High level audience information for who the outreach targets.
                            properties:
                              list_id:
                                type: string
                                title: List ID
                                description: The unique list id.
                              list_is_active:
                                type: boolean
                                title: List Status
                                description: The status of the list used, namely if it's deleted or disabled.
                                readOnly: true
                              list_name:
                                type: string
                                title: List Name
                                description: The name of the list.
                                readOnly: true
                              segment_text:
                                type: string
                                title: Segment Text
                                description: A description of the [segment](https://mailchimp.com/help/save-and-manage-segments/) used for the campaign. Formatted as a string marked up with HTML.
                                readOnly: true
                              recipient_count:
                                type: integer
                                title: Recipient Count
                                description: Count of the recipients on the associated list. Formatted as an integer.
                                readOnly: true
                              segment_opts:
                                type: object
                                title: Segment Options
                                description: An object representing all segmentation options. This object should contain a `saved_segment_id` to use an existing segment, or you can create a new segment by including both `match` and `conditions` options.
                                properties:
                                  saved_segment_id:
                                    type: integer
                                    title: Saved Segment ID
                                    description: The id for an existing saved segment.
                                  prebuilt_segment_id:
                                    type: string
                                    title: Prebuilt Segment Id
                                    description: The prebuilt segment id, if a prebuilt segment has been designated for this campaign.
                                    example: subscribers-female
                                  match:
                                    type: string
                                    title: Match Type
                                    description: Segment 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
                    

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