Mailchimp Reports API

openapi: 3.2.0
info:
  version: 3.0.91
  title: Mailchimp Marketing Reports 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: reports
paths:
  /reports:
    get:
      summary: List campaign reports
      description: Get campaign reports.
      operationId: getReports
      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: type
        x-title: Campaign Type
        in: query
        description: The campaign type.
        required: false
        schema:
          type: string
          enum:
          - regular
          - plaintext
          - absplit
          - rss
          - variate
      - name: before_send_time
        x-title: Before Send Time
        in: query
        description: 'Restrict the response to campaigns sent before the set time. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        required: false
        schema:
          type: string
          format: date-time
      - name: since_send_time
        x-title: Since Send Time
        in: query
        description: 'Restrict the response to campaigns sent after the set time. Uses ISO 8601 time format: 2015-10-21T15:41:36+00:00.'
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                title: Campaign Reports
                description: A list of reports containing campaigns marked as Sent.
                properties:
                  reports:
                    type: array
                    items:
                      type: object
                      title: Campaign Report
                      description: Report details about a sent campaign.
                      properties:
                        id:
                          type: string
                          title: Campaign ID
                          description: A string that uniquely identifies this campaign.
                        campaign_title:
                          type: string
                          title: Campaign Title
                          description: The title of the campaign.
                          readOnly: true
                        type:
                          type: string
                          title: Campaign Type
                          description: The type of campaign (regular, plain-text, ab_split, rss, automation, variate, or auto).
                        list_id:
                          type: string
                          title: List ID
                          description: The unique list id.
                          readOnly: true
                        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
                        subject_line:
                          type: string
                          title: Campaign Subject Line
                          description: The subject line for the campaign.
                          readOnly: true
                        preview_text:
                          type: string
                          title: Campaign Preview Text
                          description: The preview text for the campaign.
                        emails_sent:
                          type: integer
                          title: Emails Sent
                          description: The total number of emails sent for this campaign.
                        abuse_reports:
                          type: integer
                          title: Abuse Reports
                          description: The number of abuse reports generated for this campaign.
                        unsubscribed:
                          type: integer
                          title: Unsubscribe Count
                          description: The total number of unsubscribed members for this campaign.
                          readOnly: true
                        send_time:
                          type: string
                          format: date-time
                          title: Send Time
                          description: The date and time a campaign was sent in ISO 8601 format.
                          readOnly: true
                        rss_last_send:
                          type: string
                          format: date-time
                          title: RSS Last Send
                          description: For RSS campaigns, the date and time of the last send in ISO 8601 format.
                          readOnly: true
                        bounces:
                          type: object
                          title: Bounces
                          description: An object describing the bounce summary for the campaign.
                          properties:
                            hard_bounces:
                              type: integer
                              title: Hard Bounces
                              description: The total number of hard bounced email addresses.
                            soft_bounces:
                              type: integer
                              title: Soft Bounces
                              description: The total number of soft bounced email addresses.
                            syntax_errors:
                              type: integer
                              title: Syntax Errors
                              description: The total number of addresses that were syntax-related bounces.
                        forwards:
                          type: object
                          title: Forwards
                          description: An object describing the forwards and forward activity for the campaign.
                          properties:
                            forwards_count:
                              type: integer
                              title: Total Forwards
                              description: How many times the campaign has been forwarded.
                            forwards_opens:
                              type: integer
                              title: Forward Opens
                              description: How many times the forwarded campaign has been opened.
                        opens:
                          type: object
                          title: Opens
                          description: An object describing the open activity for the campaign.
                          properties:
                            opens_total:
                              type: integer
                              title: Total Opens
                              description: The total number of opens for a campaign.
                            proxy_excluded_opens:
                              type: integer
                              title: Proxy Excluded Opens
                              description: The total number of opens for a campaign, excluding opens from email clients that use proxies.
                            unique_opens:
                              type: integer
                              title: Unique Opens
                              description: The total number of unique opens for a campaign.
                            proxy_excluded_unique_opens:
                              type: integer
                              title: Proxy Excluded Unique Opens
                              description: The total number of unique opens for a campaign, excluding opens from email clients that use proxies.
                            open_rate:
                              type: number
                              title: Open Rate
                              description: The number of unique opens for a campaign divided by the total number of successful deliveries.
                            proxy_excluded_open_rate:
                              type: number
                              title: Proxy Excluded Open Rate
                              description: The average unique open rate for a campaign, excluding opens from email clients that use proxies.
                            last_open:
                              type: string
                              format: date-time
                              title: Last Open
                              description: The date and time of the last recorded open in ISO 8601 format.
                        clicks:
                          type: object
                          title: Clicks
                          description: An object describing the click activity for the campaign.
                          properties:
                            clicks_total:
                              type: integer
                              title: Total Clicks
                              description: The total number of clicks for the campaign.
                            unique_clicks:
                              type: integer
                              title: Unique Clicks
                              description: The total number of unique clicks for links across a campaign.
                            unique_subscriber_clicks:
                              type: integer
                              title: Unique Subscriber Clicks
                              description: The total number of subscribers who clicked on a campaign.
                            click_rate:
                              type: number
                              title: Click Rate
                              description: The number of unique clicks divided by the total number of successful deliveries.
                            last_click:
                              type: string
                              format: date-time
                              title: Last Click
                              description: The date and time of the last recorded click for the campaign in ISO 8601 format.
                        facebook_likes:
                          type: object
                          title: Facebook Likes
                          description: An object describing campaign engagement on Facebook.
                          properties:
                            recipient_likes:
                              type: integer
                              title: Recipient Likes
                              description: The number of recipients who liked the campaign on Facebook.
                            unique_likes:
                              type: integer
                              title: Unique Likes
                              description: The number of unique likes.
                            facebook_likes:
                              type: integer
                              title: Facebook Likes
                              description: The number of Facebook likes for the campaign.
                        industry_stats:
                          type: object
                          title: Industry Stats
                          description: The average campaign statistics for your industry.
                          properties:
                            type:
                              type: string
                              title: Industry Type
                              description: 'The type of business industry associated with your account. For example: retail, education, etc.'
                            open_rate:
                              type: number
                              title: Open Rate
                              description: The industry open rate.
                            click_rate:
                              type: number
                              title: Click Rate
                              description: The industry click rate.
                            bounce_rate:
                              type: number
                              title: Bounce Rate
                              description: The industry bounce rate.
                            unopen_rate:
                              type: number
                              title: Unopened Rate
                              description: The industry unopened rate.
                            unsub_rate:
                              type: number
                              title: Unsubscribe Rate
                              description: The industry unsubscribe rate.
                            abuse_rate:
                              type: number
                              title: Abuse Rate
                              description: The industry abuse rate.
                        list_stats:
                          type: object
                          title: List Stats
                          description: The average campaign statistics for your list. This won't be present if we haven't calculated it yet for this list.
                          properties:
                            sub_rate:
                              type: number
                              title: Average Subscription Rate
                              description: The average number of subscriptions per month for the list.
                              readOnly: true
                            unsub_rate:
                              type: number
                              title: Average Unsubscription Rate
                              description: The average number of unsubscriptions per month for the list.
                              readOnly: true
                            open_rate:
                              type: number
                              title: Open Rate
                              description: The average unique open rate (a percentage represented as a number between 0 and 100) per campaign for the list.
                              readOnly: true
                            proxy_excluded_open_rate:
                              type: number
                              title: Proxy Excluded Open Rate
                              description: The average unique open rate (a percentage represented as a number between 0 and 100) per campaign for the list, excluding opens from email clients that use proxies.
                              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.
                              readOnly: true
                        ab_split:
                          type: object
                          title: A/B Split Stats
                          description: General stats about different groups of an A/B Split campaign. Does not return information about Multivariate Campaigns.
                          properties:
                            a:
                              type: object
                              title: Campaign A
                              description: Stats for Campaign A.
                              properties:
                                bounces:
                                  type: integer
                                  title: Bounces
                                  description: Bounces for Campaign A.
                                abuse_reports:
                                  type: integer
                                  title: Abuse Reports
                                  description: Abuse reports for Campaign A.
                                unsubs:
                                  type: integer
                                  title: Unsubscribes
                                  description: Unsubscribes for Campaign A.
                                recipient_clicks:
                                  type: integer
                                  title: Recipient Clicks
                                  description: Recipient Clicks for Campaign A.
                                forwards:
                                  type: integer
                                  title: Forwards
                                  description: Forwards for Campaign A.
                                forwards_opens:
                                  type: integer
                                  title: Forward Opens
                                  description: Opens from forwards for Campaign A.
                                opens:
                                  type: integer
                                  title: Opens
                                  description: Opens for Campaign A.
                                last_open:
                                  type: string
                                  title: Last Open
                                  description: The last open for Campaign A.
                                unique_opens:
                                  type: integer
                                  title: Unique Opens
                                  description: Unique opens for Campaign A.
                            b:
                              type: object
                              title: Campaign B
                              description: Stats for Campaign B.
                              properties:
                                bounces:
                                  type: integer
                                  title: Bounces
                                  description: Bounces for Campaign B.
                                abuse_reports:
                                  type: integer
                                  title: Abuse Reports
                                  description: Abuse reports for Campaign B.
                                unsubs:
                                  type: integer
                                  title: Unsubscribes
                                  description: Unsubscribes for Campaign B.
                                recipient_clicks:
                                  type: integer
                                  title: Recipient Clicks
                                  description: Recipients clicks for Campaign B.
                                forwards:
                                  type: integer
                                  title: Forwards
                                  description: Forwards for Campaign B.
                                forwards_opens:
                                  type: integer
                                  title: Forward Opens
                                  description: Opens for forwards from Campaign B.
                                opens:
                                  type: integer
                                  title: Opens
                                  description: Opens for Campaign B.
                                last_open:
                                  type: string
                                  title: Last Open
                                  description: The last open for Campaign B.
                                unique_opens:
                                  type: integer
                                  title: Unique Opens
                                  description: Unique opens for Campaign B.
                        timewarp:
                          type: array
                          title: Timewarp Stats
                          description: An hourly breakdown of sends, opens, and clicks if a campaign is sent using timewarp.
                          items:
                            type: object
                            properties:
                              gmt_offset:
                                type: integer
                                title: GMT Offset
                                description: For campaigns sent with timewarp, the time zone group the member is apart of.
                              opens:
                                type: integer
                                title: Opens
                                description: The number of opens.
                              last_open:
                                type: string
                                format: date-time
                                title: Last Open
                                description: The date and time of the last open in ISO 8601 format.
                              unique_opens:
                                type: integer
                                title: Unique Opens
                                description: The number of unique opens.
                              clicks:
                                type: integer
                                title: Clicks
                                description: The number of clicks.
                              last_click:
                                type: string
                                format: date-time
                                title: Last Click
                                description: The date and time of the last click in ISO 8601 format.
                              unique_clicks:
                                type: integer
                                title: Unique Clicks
                                description: The number of unique clicks.
                              bounces:
                                type: integer
                                title: Bounces
                                description: The number of bounces.
                        timeseries:
                          type: array
                          title: Timeseries
                          description: An hourly breakdown of the performance of the campaign over the first 24 hours.
                          items:
                            type: object
                            properties:
                              timestamp:
                                type: string
                                format: date-time
                                title: Timestamp
                                description: The date and time for the series in ISO 8601 format.
                              emails_sent:
                                type: integer
                                title: Emails Sent
                                description: The number of emails sent in the timeseries.
                              unique_opens:
                                type: integer
                                title: Unique Opens
                                description: The number of unique opens in the timeseries.
                              proxy_excluded_unique_opens:
                                type: integer
                                title: Proxy Excluded Unique Opens
                                description: The number of unique opens in the timeseries, excluding opens from email clients that use proxies.
                              recipients_clicks:
                                type: integer
                                title: Recipient Clicks
                                description: The number of clicks in the timeseries.
                        share_report:
                          type: object
                          title: Share Report
                          description: The url and password for the [VIP report](https://mailchimp.com/help/share-a-campaign-report/).
                          properties:
                            share_url:
                              type: string
                              title: Report URL
                              description: The URL for the VIP report.
                              readOnly: true
                            share_password:
                              type: string
                              title: Report Password
                              description: If password protected, the password for the VIP report.
                              readOnly: true
                        ecommerce:
                          type: object
                          title: E-Commerce Report
                          description: E-Commerce stats for a campaign.
                          properties:
                            total_orders:
                              type: integer
                              title: Total Orders
                              description: The total orders for a campaign.
                              readOnly: true
                            total_spent:
                              type: number
                              title: Total Spent
                              description: The total spent for a campaign. Calculated as the sum of all order totals with no deductions.
                              readOnly: true
                            total_revenue:
                              type: number
                              title: Total Revenue
                              description: The total revenue for a campaign. Calculated as the sum of all order totals minus shipping and tax totals.
                              readOnly: true
                            currency_code:
                              type: string
                              title: Three letter currency code for this user
                              readOnly: true
                              example: USD
                        delivery_status:
                          type: object
                          title: Campaign Delivery Status
                          description: Updates on campaigns in the process of sending.
                          properties:
                            enabled:
                              type: boolean
                              title: Delivery Status Enabled
                              description: Whether Campaign Delivery Status is enabled for this account and campaign.
                              readOnly: true
                            can_cancel:
                              type: boolean
                              title: Campaign Cancelable
                              description: Whether a campaign send can be canceled.
                              readOnly: true
                            status:
                              type: string
                              title: Campaign Delivery Status
                              description: The current state of a campaign delivery.
                              enum:
                              - delivering
                              - delivered
                              - canceling
                              - canceled
                              readOnly: true
                            emails_sent:
                              type: integer
                              title: Emails Sent
                              description: The total number of emails confirmed sent for this campaign so far.
                              readOnly: true
                            emails_canceled:
                              type: integer
                              title: Emails Canceled
                              description: The total number of emails canceled for this campaign.
                              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 report resource.
                  total_items:
                    type: integer
                    title: Item Count
                    description: The total number of items matching the query regardless of pagination.
                    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
 

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