Mailchimp Messages API

swagger: '2.0'
info:
  version: 3.0.55
  title: Mailchimp Marketing Abuse Messages 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: Messages
paths:
  /conversations/{conversation_id}/messages:
    get:
      summary: Mailchimp List Messages
      description: Get messages from a specific 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 arent available using this endpoint.
      operationId: getConversationsIdMessages
      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
      - in: path
        name: conversation_id
        x-title: Conversation ID
        type: string
        required: true
        description: The unique id for the conversation.
        example: '500123'
      - name: is_read
        x-title: Is Read
        in: query
        description: Whether a conversation message has been marked as read.
        required: false
        type: string
        enum:
        - 'true'
        - 'false'
        example: example_value
      - name: before_timestamp
        x-title: Before Timestamp
        in: query
        description: 'Restrict the response to messages created 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_timestamp
        x-title: Since Timestamp
        in: query
        description: 'Restrict the response to messages created 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: Collection of Conversation Messages
            description: Messages from a specific conversation.
            properties:
              conversation_messages:
                type: array
                items:
                  type: object
                  title: Conversation Message
                  description: An individual message in a 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 message
                      readOnly: true
                    conversation_id:
                      type: string
                      title: Conversation ID
                      description: A string that identifies this message's conversation
                      readOnly: true
                    list_id:
                      type: integer
                      title: List ID
                      description: The list's web ID
                      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
                    subject:
                      type: string
                      title: Subject
                      description: The subject of this message
                    message:
                      type: string
                      title: Message
                      description: The plain-text content of the message
                    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: Conversation Messages
                description: An array of objects, each representing a conversation messages resources.
              conversation_id:
                type: string
                title: Conversation ID
                description: A string that identifies this conversation.
              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: true
      tags:
      - Messages
      x-custom-config:
        methodNameSnake: get_conversation_messages
        methodNameCamel: getConversationMessages
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /conversations/{conversation_id}/messages/{message_id}:
    get:
      summary: Mailchimp Get Message
      description: Get an individual message in a 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 arent available using this endpoint.
      operationId: getConversationsIdMessagesId
      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
      - in: path
        name: conversation_id
        x-title: Conversation ID
        type: string
        required: true
        description: The unique id for the conversation.
        example: '500123'
      - in: path
        name: message_id
        x-title: Message ID
        type: string
        required: true
        description: The unique id for the conversation message.
        example: '500123'
      responses:
        '200':
          description: ''
          schema:
            type: object
            title: Conversation Message
            description: An individual message in a 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 message
                readOnly: true
              conversation_id:
                type: string
                title: Conversation ID
                description: A string that identifies this message's conversation
                readOnly: true
              list_id:
                type: integer
                title: List ID
                description: The list's web ID
                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
              subject:
                type: string
                title: Subject
                description: The subject of this message
              message:
                type: string
                title: Message
                description: The plain-text content of the message
              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
        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: true
      tags:
      - Messages
      x-custom-config:
        methodNameSnake: get_conversation_message
        methodNameCamel: getConversationMessage
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/send:
    post:
      operationId: postMessagesSend
      summary: Mailchimp Send a Transactional Email
      description: Send a new transactional message through Mandrill. Supports HTML and plain-text content, inline images, attachments, merge variables, metadata, and per-recipient customization.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - message
              properties:
                key:
                  type: string
                  description: A valid Mandrill API key.
                message:
                  $ref: '#/components/schemas/MessagePayload'
                async:
                  type: boolean
                  description: Enable background sending mode optimized for bulk sending. In async mode, the response will not include per-recipient status, and failures will be handled by retry or webhook.
                  default: false
                ip_pool:
                  type: string
                  description: The name of the dedicated IP pool that should be used to send this message.
                send_at:
                  type: string
                  format: date-time
                  description: Schedule the message for future delivery. The date/time must be in UTC and formatted as YYYY-MM-DD HH:MM:SS. Messages can be scheduled up to 7 days in advance.
            examples:
              PostmessagessendRequestExample:
                summary: Default postMessagesSend request
                x-microcks-default: true
                value:
                  key: example_value
                  message:
                    html: example_value
                    text: example_value
                    subject: example_value
                    from_email: user@example.com
                    from_name: example_value
                    to:
                    - email: user@example.com
                      name: Example Title
                      type: to
                    headers: example_value
                    important: true
                    track_opens: true
                    track_clicks: true
                    auto_text: true
                    auto_html: true
                    inline_css: true
                    url_strip_qs: https://www.example.com
                    preserve_recipients: true
                    view_content_link: true
                    bcc_address: example_value
                    tracking_domain: example_value
                    signing_domain: example_value
                    return_path_domain: example_value
                    merge: true
                    merge_language: mailchimp
                    global_merge_vars:
                    - name: Example Title
                      content: example_value
                    merge_vars:
                    - rcpt: example_value
                      vars: {}
                    tags:
                    - example_value
                    subaccount: example_value
                    google_analytics_domains:
                    - example_value
                    google_analytics_campaign: example_value
                    metadata: example_value
                    recipient_metadata:
                    - rcpt: example_value
                      values: example_value
                    attachments:
                    - type: example_value
                      name: Example Title
                      content: example_value
                    images:
                    - type: example_value
                      name: Example Title
                      content: example_value
                  async: true
                  ip_pool: example_value
                  send_at: '2026-01-15T10:30:00Z'
      responses:
        '200':
          description: An array of sending results, one per recipient. Each object contains the email address, status, reject reason (if any), and the message ID.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SendResult'
              examples:
                Postmessagessend200Example:
                  summary: Default postMessagesSend 200 response
                  x-microcks-default: true
                  value:
                  - email: user@example.com
                    status: sent
                    reject_reason: hard-bounce
                    queued_reason: example_value
                    _id: '500123'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/InvalidKeyError'
        '500':
          $ref: '#/components/responses/GeneralError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/send-template:
    post:
      operationId: postMessagesSendTemplate
      summary: Mailchimp Send an Email Using a Template
      description: Send a new transactional message using a stored template. Template content blocks can be overridden with the template_content parameter. Merge variables in the template are populated from the message object.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - template_name
              - template_content
              - message
              properties:
                key:
                  type: string
                  description: A valid Mandrill API key.
                template_name:
                  type: string
                  description: The slug or name of the template stored in Mandrill to use for this message.
                template_content:
                  type: array
                  description: An array of objects with name/content pairs for injecting content into editable regions defined in the template using mc:edit attributes.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: The name of the mc:edit content block to set.
                      content:
                        type: string
                        description: The HTML content to replace the block with.
                message:
                  $ref: '#/components/schemas/MessagePayload'
                async:
                  type: boolean
                  default: false
                  description: Enable background sending mode.
                ip_pool:
                  type: string
                  description: The name of the dedicated IP pool to use.
                send_at:
                  type: string
                  format: date-time
                  description: Schedule message for future delivery in UTC.
            examples:
              PostmessagessendtemplateRequestExample:
                summary: Default postMessagesSendTemplate request
                x-microcks-default: true
                value:
                  key: example_value
                  template_name: example_value
                  template_content:
                  - name: Example Title
                    content: example_value
                  message:
                    html: example_value
                    text: example_value
                    subject: example_value
                    from_email: user@example.com
                    from_name: example_value
                    to:
                    - email: user@example.com
                      name: Example Title
                      type: to
                    headers: example_value
                    important: true
                    track_opens: true
                    track_clicks: true
                    auto_text: true
                    auto_html: true
                    inline_css: true
                    url_strip_qs: https://www.example.com
                    preserve_recipients: true
                    view_content_link: true
                    bcc_address: example_value
                    tracking_domain: example_value
                    signing_domain: example_value
                    return_path_domain: example_value
                    merge: true
                    merge_language: mailchimp
                    global_merge_vars:
                    - name: Example Title
                      content: example_value
                    merge_vars:
                    - rcpt: example_value
                      vars: {}
                    tags:
                    - example_value
                    subaccount: example_value
                    google_analytics_domains:
                    - example_value
                    google_analytics_campaign: example_value
                    metadata: example_value
                    recipient_metadata:
                    - rcpt: example_value
                      values: example_value
                    attachments:
                    - type: example_value
                      name: Example Title
                      content: example_value
                    images:
                    - type: example_value
                      name: Example Title
                      content: example_value
                  async: true
                  ip_pool: example_value
                  send_at: '2026-01-15T10:30:00Z'
      responses:
        '200':
          description: An array of sending results, one per recipient.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SendResult'
              examples:
                Postmessagessendtemplate200Example:
                  summary: Default postMessagesSendTemplate 200 response
                  x-microcks-default: true
                  value:
                  - email: user@example.com
                    status: sent
                    reject_reason: hard-bounce
                    queued_reason: example_value
                    _id: '500123'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/InvalidKeyError'
        '500':
          $ref: '#/components/responses/GeneralError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/search:
    post:
      operationId: postMessagesSearch
      summary: Mailchimp Search Sent Messages
      description: Search recently sent messages and return matching results. You can filter by sending status, sender, tags, recipient, subject, and date range. Results are limited to the last 7 days.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              properties:
                key:
                  type: string
                  description: A valid Mandrill API key.
                query:
                  type: string
                  description: Search terms to filter results. Supports full-text search across message subject and email addresses.
                date_from:
                  type: string
                  format: date-time
                  description: Start date for the search range (UTC).
                date_to:
                  type: string
                  format: date-time
                  description: End date for the search range (UTC).
                tags:
                  type: array
                  items:
                    type: string
                  description: Tags that must be present on matching messages.
                senders:
                  type: array
                  items:
                    type: string
                  description: Sender addresses to filter by.
                api_keys:
              

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