Mailchimp Transactional API

openapi: 3.1.0
info:
  title: Mailchimp Transactional API
  version: 1.0.0
  description: >-
    The Mailchimp Transactional API (formerly Mandrill) enables sending
    personalized, one-to-one transactional emails such as password resets,
    order confirmations, and welcome messages. It provides high-deliverability
    email infrastructure with detailed analytics, templates, and webhook support.
  contact:
    name: Mailchimp API Support
    email: [email protected]
    url: https://mailchimp.com/developer/transactional/
  license:
    name: Mailchimp API Use Policy
    url: https://mailchimp.com/legal/api_use/
  termsOfService: https://mailchimp.com/legal/terms/

servers:
- url: https://mandrillapp.com/api/1.0
  description: Mailchimp Transactional (Mandrill) Production API

security:
- apiKey: []

tags:
- name: Allowlists
  description: >-
    Manage the allowlist of email addresses that bypass the rejection
    blacklist.
- name: Exports
  description: Request and download data exports for messages, rejects, and allowlists.
- name: IPs
  description: Manage dedicated IP addresses associated with the account.
- name: Messages
  description: Send and search transactional messages, and retrieve message details.
- name: Metadata
  description: >-
    Manage custom metadata fields that can be attached to messages for
    tracking and filtering.

- name: Rejects
  description: >-
    Manage the rejection blacklist, which prevents delivery to addresses
    that have previously bounced or been reported as spam.
- name: Senders
  description: >-
    Retrieve sender information and statistics for verified sending domains
    and email addresses.
- name: Subaccounts
  description: >-
    Manage subaccounts for organizing sending and reporting within a single
    Mandrill account.
- name: Templates
  description: >-
    Manage reusable email templates stored on the Mandrill server for use
    when sending transactional messages.
- name: Users
  description: Retrieve information about the authenticated Mandrill account.
- name: Webhooks
  description: Manage webhooks that receive event notifications for sent messages.
paths:
  /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: [email protected]
                    from_name: example_value
                    to:
                    - email: [email protected]
                      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: [email protected]
                    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: [email protected]
                    from_name: example_value
                    to:
                    - email: [email protected]
                      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: [email protected]
                    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:
                  type: array
                  items:
                    type: string
                  description: API keys to filter by for subaccount isolation.
                limit:
                  type: integer
                  default: 100
                  description: Maximum number of results to return (max 1000).
            examples:
              PostmessagessearchRequestExample:
                summary: Default postMessagesSearch request
                x-microcks-default: true
                value:
                  key: example_value
                  query: example_value
                  date_from: '2026-01-15T10:30:00Z'
                  date_to: '2026-01-15T10:30:00Z'
                  tags:
                  - example_value
                  senders:
                  - example_value
                  api_keys:
                  - example_value
                  limit: 10
      responses:
        '200':
          description: An array of message info objects matching the search criteria.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MessageInfo'
              examples:
                Postmessagessearch200Example:
                  summary: Default postMessagesSearch 200 response
                  x-microcks-default: true
                  value:
                  - ts: 10
                    _id: '500123'
                    sender: example_value
                    template: example_value
                    subject: example_value
                    email: [email protected]
                    tags:
                    - example_value
                    opens: 10
                    opens_detail:
                    - ts: 10
                      ip: example_value
                      location: example_value
                      ua: example_value
                    clicks: 10
                    clicks_detail:
                    - ts: 10
                      url: https://www.example.com
                      ip: example_value
                      location: example_value
                      ua: example_value
                    state: sent
                    metadata: example_value
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/InvalidKeyError'
        '500':
          $ref: '#/components/responses/GeneralError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/search-time-series:
    post:
      operationId: postMessagesSearchTimeSeries
      summary: Mailchimp Search Message Time Series
      description: >-
        Search the content of recently sent messages and return aggregated
        hourly statistics for matching messages over time.
      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.
                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.
            examples:
              PostmessagessearchtimeseriesRequestExample:
                summary: Default postMessagesSearchTimeSeries request
                x-microcks-default: true
                value:
                  key: example_value
                  query: example_value
                  date_from: '2026-01-15T10:30:00Z'
                  date_to: '2026-01-15T10:30:00Z'
                  tags:
                  - example_value
                  senders:
                  - example_value
      responses:
        '200':
          description: An array of time series data points with hourly statistics.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeSeries'
              examples:
                Postmessagessearchtimeseries200Example:
                  summary: Default postMessagesSearchTimeSeries 200 response
                  x-microcks-default: true
                  value:
                  - time: '2026-01-15T10:30:00Z'
                    sent: 10
                    hard_bounces: 10
                    soft_bounces: 10
                    rejects: 10
                    complaints: 10
                    unsubs: 10
                    opens: 10
                    unique_opens: 10
                    clicks: 10
                    unique_clicks: 10
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/InvalidKeyError'
        '500':
          $ref: '#/components/responses/GeneralError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/info:
    post:
      operationId: postMessagesInfo
      summary: Mailchimp Get Message Info
      description: >-
        Get the information for a single recently sent message including
        delivery status, open/click tracking, and metadata.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - id
              properties:
                key:
                  type: string
                  description: A valid Mandrill API key.
                id:
                  type: string
                  description: The unique message ID returned from a send call.
            examples:
              PostmessagesinfoRequestExample:
                summary: Default postMessagesInfo request
                x-microcks-default: true
                value:
                  key: example_value
                  id: abc123
      responses:
        '200':
          description: Detailed information about the message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDetail'
              examples:
                Postmessagesinfo200Example:
                  summary: Default postMessagesInfo 200 response
                  x-microcks-default: true
                  value: {}
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/InvalidKeyError'
        '500':
          $ref: '#/components/responses/GeneralError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/content:
    post:
      operationId: postMessagesContent
      summary: Mailchimp Get Message Content
      description: >-
        Get the full content of a recently sent message including the HTML
        body, text body, headers, and attachments.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - id
              properties:
                key:
                  type: string
                  description: A valid Mandrill API key.
                id:
                  type: string
                  description: The unique message ID.
            examples:
              PostmessagescontentRequestExample:
                summary: Default postMessagesContent request
                x-microcks-default: true
                value:
                  key: example_value
                  id: abc123
      responses:
        '200':
          description: The full content of the message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageContent'
              examples:
                Postmessagescontent200Example:
                  summary: Default postMessagesContent 200 response
                  x-microcks-default: true
                  value:
                    ts: 10
                    _id: '500123'
                    from_email: [email protected]
                    from_name: example_value
                    subject: example_value
                    to:
                      email: [email protected]
                      name: Example Title
                    tags:
                    - example_value
                    headers: example_value
                    text: example_value
                    html: example_value
                    attachments:
                    - name: Example Title
                      type: example_value
                      content: example_value
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/InvalidKeyError'
        '500':
          $ref: '#/components/responses/GeneralError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/parse:
    post:
      operationId: postMessagesParse
      summary: Mailchimp Parse a Raw Mime Message
      description: >-
        Parse the full MIME document for an email message, returning the
        subject, recipients, HTML body, text body, headers, and attachments.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - raw_message
              properties:
                key:
                  type: string
                  description: A valid Mandrill API key.
                raw_message:
                  type: string
                  description: The full MIME document of the message to parse.
            examples:
              PostmessagesparseRequestExample:
                summary: Default postMessagesParse request
                x-microcks-default: true
                value:
                  key: example_value
                  raw_message: example_value
      responses:
        '200':
          description: The parsed message content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParsedMessage'
              examples:
                Postmessagesparse200Example:
                  summary: Default postMessagesParse 200 response
                  x-microcks-default: true
                  value:
                    subject: example_value
                    from_email: [email protected]
                    from_name: example_value
                    to:
                    - email: [email protected]
                      name: Example Title
                    headers: example_value
                    text: example_value
                    html: example_value
                    attachments:
                    - name: Example Title
                      type: example_value
                      content: example_value
                    images:
                    - name: Example Title
                      type: example_value
                      content: example_value
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/InvalidKeyError'
        '500':
          $ref: '#/components/responses/GeneralError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /messages/send-raw:
    post:
      operationId: postMessagesSendRaw
      summary: Mailchimp Send a Raw Mime Message
      description: >-
        Take a raw MIME document and send it exactly as provided. Mandrill
        will not modify the message content, but will track opens and clicks
        if the appropriate headers are included.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              - raw_message
              properties:
                key:
                  type: string
                  description: A valid Mandrill API key.
                raw_message:
                  type: string
                  description: The full MIME document of the message to send.
                from_email:
                  type: string
                  format: email
                  description: >-
                    Override the from address in the raw message. If not
                    specified, the from address in the raw message is used.
                from_name:
                  type: string
                  description: Override the from name in the raw message.
                to:
                  type: array
                  items:
                    type: string
                    format: email
                  description: >-
                    Override the recipients in the raw message. If not
                    provided, recipients from the MIME headers are used.
                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.
                return_path_domain:
                  type: string
                  description: Custom domain for the return-path header.
            examples:
              PostmessagessendrawRequestExample:
                summary: Default postMessagesSendRaw request
                x-microcks-default: true
                value:
                  key: example_value
                  raw_message: example_value
                  from_email: [email protected]
                  from_name: example_value
                  to:
                  - example_value
                  async: true
                  ip_pool: example_value
                  send_at: '2026-01-15T10:30:00Z'
                  return_path_domain: example_value
      responses:
        '200':
          description: An array of sending results, one per recipient.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SendResult'
              examples:
                Postmessagessendraw200Example:
                  summary: Default postMessagesSendRaw 200 response
                  x-microcks-default: true
                  value:
                  - email: [email protected]
                    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/list-scheduled:
    post:
      operationId: postMessagesListScheduled
      summary: Mailchimp List Scheduled Messages
      description: >-
        Get a list of messages that are scheduled for future delivery. Messages
        can be scheduled up to 7 days in advance.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key
              properties:
                key:
                  type: string
                  description: A valid Mandrill API key.
                to:
                  type: string
                  format: email
                  description: >-
                    Optional recipient email address to restrict results to
                    messages scheduled for a specific recipient.
            examples:
              PostmessageslistscheduledRequestExample:
                summary: Default postMessagesListScheduled request
                x-microcks-default: true
                value:
                  key: example_value
                  to: example_value
      responses:
        '200':
          description: An array of scheduled message objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScheduledMessage'
              examples:
                Postmessageslistscheduled200Example:
                  summary: Default postMessagesListScheduled 200 response
                  x-microcks-default: true
                  value:
                  - _id: '500123'
                    created_at: '2026-01-15T10:30:00Z'
                    send_at: '2026-01-15T10:30:00Z'
                    from_email: [email protected]
                    to: example_value
                    subject: ex

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