Mailchimp Conversations API

openapi: 3.2.0
info:
  version: 3.0.91
  title: Mailchimp Marketing Conversations 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: conversations
paths:
  /conversations:
    get:
      summary: List conversations
      description: Get a list of conversations for the account. Conversations has been deprecated in favor of Inbox and these endpoints don't include Inbox data. Past Conversations are still available via this endpoint, but new campaign replies and other Inbox messages aren’t available using this endpoint.
      operationId: getConversations
      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: has_unread_messages
        x-title: Has Unread Messages
        in: query
        description: Whether the conversation has any unread messages.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: list_id
        x-title: List ID
        in: query
        description: The unique id for the list.
        required: false
        schema:
          type: string
      - name: campaign_id
        x-title: Campaign ID
        in: query
        description: The unique id for the campaign.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                title: Tracked Conversations
                description: A collection of this account's tracked conversations.
                properties:
                  conversations:
                    type: array
                    items:
                      type: object
                      title: Conversation
                      description: Details about an individual conversation. Conversation tracking is a feature available to paid accounts that lets you view replies to your campaigns in your Mailchimp account.
                      properties:
                        id:
                          type: string
                          title: ID
                          description: A string that uniquely identifies this conversation.
                          readOnly: true
                        message_count:
                          type: integer
                          title: Message Count
                          description: The total number of messages in this conversation.
                          readOnly: true
                        campaign_id:
                          type: string
                          title: Campaign ID
                          description: The unique identifier of the campaign for this conversation.
                          readOnly: true
                        list_id:
                          type: string
                          title: List ID
                          description: The unique identifier of the list for this conversation.
                          readOnly: true
                        unread_messages:
                          type: integer
                          title: Unread Messages
                          description: The number of unread messages in this conversation.
                          readOnly: true
                        from_label:
                          type: string
                          title: From Label
                          description: A label representing the sender of this message.
                          readOnly: true
                        from_email:
                          type: string
                          title: From Email
                          description: A label representing the email of the sender of this message.
                          readOnly: true
                        subject:
                          type: string
                          title: Subject
                          description: The subject of the message.
                          readOnly: true
                        last_message:
                          type: object
                          title: Last Message
                          description: The most recent message in the conversation.
                          properties:
                            from_label:
                              type: string
                              title: From Label
                              description: A label representing the sender of this message.
                              readOnly: true
                            from_email:
                              type: string
                              title: From Email
                              description: A label representing the email of the sender of this message.
                              readOnly: true
                            subject:
                              type: string
                              title: Subject
                              description: The subject of this message.
                              readOnly: true
                            message:
                              type: string
                              title: Message
                              description: The plain-text content of the message.
                              readOnly: true
                            read:
                              type: boolean
                              title: Read
                              description: Whether this message has been marked as read.
                            timestamp:
                              type: string
                              title: Timestamp
                              description: The date and time the message was either sent or received in ISO 8601 format.
                              format: date-time
                              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: Conversations
                    description: A list of conversations.
                  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
            application/problem+json:
              schema:
                type: object
                title: Tracked Conversations
                description: A collection of this account's tracked conversations.
                properties:
                  conversations:
                    type: array
                    items:
                      type: object
                      title: Conversation
                      description: Details about an individual conversation. Conversation tracking is a feature available to paid accounts that lets you view replies to your campaigns in your Mailchimp account.
                      properties:
                        id:
                          type: string
                          title: ID
                          description: A string that uniquely identifies this conversation.
                          readOnly: true
                        message_count:
                          type: integer
                          title: Message Count
                          description: The total number of messages in this conversation.
                          readOnly: true
                        campaign_id:
                          type: string
                          title: Campaign ID
                          description: The unique identifier of the campaign for this conversation.
                          readOnly: true
                        list_id:
                          type: string
                          title: List ID
                          description: The unique identifier of the list for this conversation.
                          readOnly: true
                        unread_messages:
                          type: integer
                          title: Unread Messages
                          description: The number of unread messages in this conversation.
                          readOnly: true
                        from_label:
                          type: string
                          title: From Label
                          description: A label representing the sender of this message.
                          readOnly: true
                        from_email:
                          type: string
                          title: From Email
                          description: A label representing the email of the sender of this message.
                          readOnly: true
                        subject:
                          type: string
                          title: Subject
                          description: The subject of the message.
                          readOnly: true
                        last_message:
                          type: object
                          title: Last Message
                          description: The most recent message in the conversation.
                          properties:
                            from_label:
                              type: string
                              title: From Label
                              description: A label representing the sender of this message.
                              readOnly: true
                            from_email:
                              type: string
                              title: From Email
                              description: A label representing the email of the sender of this message.
                              readOnly: true
                            subject:
                              type: string
                              title: Subject
                              description: The subject of this message.
                              readOnly: true
                            message:
                              type: string
                              title: Message
                              description: The plain-text content of the message.
                              readOnly: true
                            read:
                              type: boolean
                              title: Read
                              description: Whether this message has been marked as read.
                            timestamp:
                              type: string
                              title: Timestamp
                              description: The date and time the message was either sent or received in ISO 8601 format.
                              format: date-time
                              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: Conversations
                    description: A list of conversations.
                  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.
          content:
            application/json:
              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
            application/problem+json:
              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: true
      tags:
      - conversations
      x-custom-config:
        methodNameSnake: list
        methodNameCamel: list
  /conversations/{conversation_id}:
    get:
      summary: Get conversation
      description: Get details about an individual conversation. Conversations has been deprecated in favor of Inbox and these endpoints don't include Inbox data. Past Conversations are still available via this endpoint, but new campaign replies and other Inbox messages aren’t available using this endpoint.
      operationId: getConversationsId
      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
      - in: path
        name: conversation_id
        x-title: Conversation ID
        required: true
        description: The unique id for the conversation.
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                title: Conversation
                description: Details about an individual conversation. Conversation tracking is a feature available to paid accounts that lets you view replies to your campaigns in your Mailchimp account.
                properties:
                  id:
                    type: string
                    title: ID
                    description: A string that uniquely identifies this conversation.
                    readOnly: true
                  message_count:
                    type: integer
                    title: Message Count
                    description: The total number of messages in this conversation.
                    readOnly: true
                  campaign_id:
                    type: string
                    title: Campaign ID
                    description: The unique identifier of the campaign for this conversation.
                    readOnly: true
                  list_id:
                    type: string
                    title: List ID
                    description: The unique identifier of the list for this conversation.
                    readOnly: true
                  unread_messages:
                    type: integer
                    title: Unread Messages
                    description: The number of unread messages in this conversation.
                    readOnly: true
                  from_label:
                    type: string
                    title: From Label
                    description: A label representing the sender of this message.
                    readOnly: true
                  from_email:
                    type: string
                    title: From Email
                    description: A label representing the email of the sender of this message.
                    readOnly: true
                  subject:
                    type: string
                    title: Subject
                    description: The subject of the message.
                    readOnly: true
                  last_message:
                    type: object
                    title: Last Message
                    description: The most recent message in the conversation.
                    properties:
                      from_label:
                        type: string
                        title: From Label
                        description: A label representing the sender of this message.
                        readOnly: true
                      from_email:
                        type: string
                        title: From Email
                        description: A label representing the email of the sender of this message.
                        readOnly: true
                      subject:
                        type: string
                        title: Subject
                        description: The subject of this message.
                        readOnly: true
                      message:
                        type: string
                        title: Message
                        description: The plain-text content of the message.
                        readOnly: true
                      read:
                        type: boolean
                        title: Read
                        description: Whether this message has been marked as read.
                      timestamp:
                        type: string
                        title: Timestamp
                        description: The date and time the message was either sent or received in ISO 8601 format.
                        format: date-time
                        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:
                     

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