Mailchimp Reports API

swagger: '2.0'
info:
  version: 3.0.55
  title: Mailchimp Marketing Abuse 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
  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: Reports
paths:
  /lists/{list_id}/abuse-reports:
    get:
      summary: Mailchimp List Abuse Reports
      description: Get all abuse reports for a specific list.
      operationId: getListsIdAbuseReports
      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'
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Abuse Complaints
            description: A collection of abuse complaints for a specific list. An abuse complaint occurs when your recipient clicks to 'report spam' in their email program.
            properties:
              abuse_reports:
                type: array
                items:
                  type: object
                  title: Abuse Complaint
                  description: Details of abuse complaints for a specific list. An abuse complaint occurs when your recipient clicks to 'report spam' in their email program.
                  properties:
                    id:
                      type: integer
                      title: Abuse Report ID
                      description: The id for the abuse report
                      readOnly: true
                    campaign_id:
                      type: string
                      title: Campaign ID
                      description: The campaign id for the abuse report
                      readOnly: true
                    list_id:
                      type: string
                      title: List ID
                      description: The list id for the abuse report.
                      readOnly: true
                    email_id:
                      type: string
                      title: Email Hash
                      description: The MD5 hash of the lowercase version of the list member's email address.
                      readOnly: true
                    email_address:
                      type: string
                      title: Email Address
                      description: Email address for a subscriber.
                      readOnly: true
                    merge_fields:
                      type: object
                      title: Merge Fields
                      description: A dictionary of merge fields where the keys are the merge tags. See the [Merge Fields documentation](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for more about the structure.
                      additionalProperties:
                        description: This object's keys are merge tags (like FNAME). It's values are the values to be added to the merge field.
                    vip:
                      type: boolean
                      title: VIP
                      description: '[VIP status](https://mailchimp.com/help/designate-and-send-to-vip-contacts/) for subscriber.'
                      readOnly: true
                    date:
                      type: string
                      title: Date
                      description: Date for the abuse report
                      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: Abuse Reports
                description: An array of objects, each representing an abuse report resource.
              list_id:
                type: string
                title: List ID
                description: The list id for the abuse report.
              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
                    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
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Reports
      x-custom-config:
        methodNameSnake: get_list_abuse_reports
        methodNameCamel: getListAbuseReports
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /lists/{list_id}/abuse-reports/{report_id}:
    get:
      summary: Mailchimp Get Abuse Report
      description: Get details about a specific abuse report.
      operationId: getListsIdAbuseReportsId
      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: report_id
        in: path
        required: true
        type: string
        description: The id for the abuse report.
        example: '500123'
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Abuse Complaint
            description: Details of abuse complaints for a specific list. An abuse complaint occurs when your recipient clicks to 'report spam' in their email program.
            properties:
              id:
                type: integer
                title: Abuse Report ID
                description: The id for the abuse report
                readOnly: true
              campaign_id:
                type: string
                title: Campaign ID
                description: The campaign id for the abuse report
                readOnly: true
              list_id:
                type: string
                title: List ID
                description: The list id for the abuse report.
                readOnly: true
              email_id:
                type: string
                title: Email Hash
                description: The MD5 hash of the lowercase version of the list member's email address.
                readOnly: true
              email_address:
                type: string
                title: Email Address
                description: Email address for a subscriber.
                readOnly: true
              merge_fields:
                type: object
                title: Merge Fields
                description: A dictionary of merge fields where the keys are the merge tags. See the [Merge Fields documentation](https://mailchimp.com/developer/marketing/docs/merge-fields/#structure) for more about the structure.
                additionalProperties:
                  description: This object's keys are merge tags (like FNAME). It's values are the values to be added to the merge field.
              vip:
                type: boolean
                title: VIP
                description: '[VIP status](https://mailchimp.com/help/designate-and-send-to-vip-contacts/) for subscriber.'
                readOnly: true
              date:
                type: string
                title: Date
                description: Date for the abuse report
                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
        default:
          description: An error generated by the Mailchimp API.
          schema:
            type: object
            title: Problem Detail Document
            description: An error generated by the Mailchimp API. Conforms to IETF draft 'draft-nottingham-http-problem-06'.
            required:
            - type
            - title
            - status
            - detail
            - instance
            properties:
              type:
                type: string
                title: Problem Type
                description: An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
                example: https://mailchimp.com/developer/marketing/docs/errors/
              title:
                type: string
                title: Error Title
                description: A short, human-readable summary of the problem type. It shouldn't change based on the occurrence of the problem, except for purposes of localization.
                example: Resource Not Found
              status:
                type: integer
                title: HTTP Status Code
                description: The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
                example: 404
              detail:
                type: string
                title: Error Message
                description: A human-readable explanation specific to this occurrence of the problem. [Learn more about errors](/developer/guides/get-started-with-mailchimp-api-3/#Errors).
                example: The requested resource could not be found.
              instance:
                type: string
                title: Instance ID
                description: A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
                example: 995c5cb0-3280-4a6e-808b-3b096d0bb219
      deprecated: false
      tags:
      - Reports
      x-custom-config:
        methodNameSnake: get_list_abuse_report_details
        methodNameCamel: getListAbuseReportDetails
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /reports:
    get:
      summary: Mailchimp 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
        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: type
        x-title: Campaign Type
        in: query
        description: The campaign type.
        required: false
        type: string
        enum:
        - regular
        - plaintext
        - absplit
        - rss
        - variate
        example: example_value
      - 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.'
        type: string
        format: date-time
        required: false
        example: example_value
      - 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.'
        type: string
        format: date-time
        required: false
        example: example_value
      responses:
        '200':
          description: ''
          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.
                        unique_opens:
                          type: integer
                          title: Unique Opens
                          description: The total number of unique opens.
                        open_rate:
                          type: number
                          title: Open Rate
                          description: The number of unique opens divided by the total number of successful deliveries.
                        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
                   

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