Postmark Messages API API

openapi: 3.2.0
info:
  title: Postmark Server Messages API
  description: 'Postmark makes sending and receiving email

    incredibly easy.

    '
  version: 1.0.0
servers:
- url: https://api.postmarkapp.com/
tags:
- name: Messages API
paths:
  /messages/outbound:
    get:
      operationId: searchOutboundMessages
      tags:
      - Messages API
      summary: Postmark Outbound message search
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: count
        description: Number of messages to return per request. Max 500.
        in: query
        required: true
        schema:
          type: integer
      - name: offset
        description: Number of messages to skip
        required: true
        in: query
        schema:
          type: integer
      - name: recipient
        description: Filter by the user who was receiving the email
        in: query
        schema:
          type: string
          format: email
      - name: fromemail
        description: Filter by the sender email address
        in: query
        schema:
          type: string
          format: email
      - name: tag
        in: query
        description: Filter by tag
        schema:
          type: string
      - name: status
        in: query
        description: Filter by status (`queued` or `sent`)
        schema:
          type: string
          enum:
          - queued
          - sent
      - name: todate
        in: query
        description: Filter messages up to the date specified. e.g. `2014-02-01`
        schema:
          type: string
          format: date
      - name: fromdate
        description: Filter messages starting from the date specified. e.g. `2014-02-01`
        in: query
        schema:
          type: string
          format: date
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundSearchResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/outbound/{messageid}/details:
    get:
      operationId: getOutboundMessageDetails
      tags:
      - Messages API
      summary: Postmark Outbound message details
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: messageid
        description: The ID of the message for which to retrieve details.
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundMessageDetailsResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/outbound/{messageid}/dump:
    get:
      operationId: getOutboundMessageDump
      tags:
      - Messages API
      summary: Postmark Outbound message dump
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: messageid
        description: The ID of the message for which to retrieve a dump.
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundMessageDumpResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/inbound:
    get:
      operationId: searchInboundMessages
      tags:
      - Messages API
      summary: Postmark Inbound message search
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: count
        in: query
        required: true
        description: Number of messages to return per request. Max 500.
        schema:
          type: integer
      - name: offset
        description: Number of messages to skip
        required: true
        in: query
        schema:
          type: integer
      - name: recipient
        description: Filter by the user who was receiving the email
        in: query
        schema:
          type: string
          format: email
      - name: fromemail
        description: Filter by the sender email address
        in: query
        schema:
          type: string
          format: email
      - name: subject
        description: Filter by email subject
        in: query
        schema:
          type: string
      - name: mailboxhash
        description: Filter by mailboxhash
        in: query
        schema:
          type: string
      - name: tag
        in: query
        description: Filter by tag
        schema:
          type: string
      - name: status
        description: Filter by status (`blocked`, `processed`, `queued`, `failed`, `scheduled`)
        in: query
        schema:
          type: string
          enum:
          - blocked
          - processed
          - queued
          - failed
          - scheduled
      - name: todate
        in: query
        description: Filter messages up to the date specified. e.g. `2014-02-01`
        schema:
          type: string
          format: date
      - name: fromdate
        in: query
        description: Filter messages starting from the date specified. e.g. `2014-02-01`
        schema:
          type: string
          format: date
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundSearchResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/inbound/{messageid}/details:
    get:
      operationId: getInboundMessageDetails
      tags:
      - Messages API
      summary: Postmark Inbound message details
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: messageid
        description: The ID of the message for which to details will be retrieved.
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundMessageFullDetailsResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/inbound/{messageid}/bypass:
    put:
      operationId: bypassRulesForInboundMessage
      tags:
      - Messages API
      summary: Postmark Bypass rules for a blocked inbound message
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: messageid
        description: The ID of the message which should bypass inbound rules.
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardPostmarkResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/inbound/{messageid}/retry:
    put:
      operationId: retryInboundMessageProcessing
      tags:
      - Messages API
      summary: Postmark Retry a failed inbound message for processing
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: messageid
        in: path
        description: The ID of the inbound message on which we should retry processing.
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardPostmarkResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/outbound/opens:
    get:
      operationId: searchOpensForOutboundMessages
      tags:
      - Messages API
      summary: Postmark Opens for all messages
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: count
        in: query
        description: Number of message opens to return per request. Max 500.
        required: true
        schema:
          type: integer
      - name: offset
        description: Number of messages to skip
        in: query
        required: true
        schema:
          type: integer
      - name: recipient
        description: Filter by To, Cc, Bcc
        in: query
        required: false
        schema:
          type: string
      - name: tag
        description: Filter by tag
        in: query
        required: false
        schema:
          type: string
      - name: client_name
        description: Filter by client name, i.e. Outlook, Gmail
        in: query
        required: false
        schema:
          type: string
      - name: client_company
        description: Filter by company, i.e. Microsoft, Apple, Google
        in: query
        required: false
        schema:
          type: string
      - name: client_family
        description: Filter by client family, i.e. OS X, Chrome
        in: query
        required: false
        schema:
          type: string
      - name: os_name
        description: Filter by full OS name and specific version, i.e. OS X 10.9 Mavericks, Windows 7
        in: query
        required: false
        schema:
          type: string
      - name: os_family
        description: Filter by kind of OS used without specific version, i.e. OS X, Windows
        in: query
        required: false
        schema:
          type: string
      - name: os_company
        description: Filter by company which produced the OS, i.e. Apple Computer, Inc., Microsoft Corporation
        in: query
        required: false
        schema:
          type: string
      - name: platform
        description: Filter by platform, i.e. webmail, desktop, mobile
        in: query
        required: false
        schema:
          type: string
      - name: country
        description: Filter by country messages were opened in, i.e. Denmark, Russia
        in: query
        required: false
        schema:
          type: string
      - name: region
        description: Filter by full name of region messages were opened in, i.e. Moscow, New York
        in: query
        required: false
        schema:
          type: string
      - name: city
        description: Filter by full name of region messages were opened in, i.e. Moscow, New York
        in: query
        required: false
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageOpenSearchResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/outbound/opens/{messageid}:
    get:
      operationId: getOpensForSingleOutboundMessage
      tags:
      - Messages API
      summary: Postmark Retrieve Message Opens
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: messageid
        description: The ID of the Outbound Message for which open statistics should be retrieved.
        in: path
        required: true
        schema:
          type: string
      - name: count
        in: query
        description: Number of message opens to return per request. Max 500.
        required: true
        schema:
          type: integer
          default: 1
          maximum: 500
          minimum: 1
      - name: offset
        in: query
        description: Number of messages to skip.
        required: true
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageOpenSearchResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/outbound/clicks:
    get:
      operationId: searchClicksForOutboundMessages
      tags:
      - Messages API
      summary: Postmark Clicks for a all messages
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: count
        in: query
        description: Number of message clicks to return per request. Max 500.
        required: true
        schema:
          type: integer
      - name: offset
        description: Number of messages to skip
        in: query
        required: true
        schema:
          type: integer
      - name: recipient
        description: Filter by To, Cc, Bcc
        in: query
        required: false
        schema:
          type: string
      - name: tag
        description: Filter by tag
        in: query
        required: false
        schema:
          type: string
      - name: client_name
        description: Filter by client name, i.e. Outlook, Gmail
        in: query
        required: false
        schema:
          type: string
      - name: client_company
        description: Filter by company, i.e. Microsoft, Apple, Google
        in: query
        required: false
        schema:
          type: string
      - name: client_family
        description: Filter by client family, i.e. OS X, Chrome
        in: query
        required: false
        schema:
          type: string
      - name: os_name
        description: Filter by full OS name and specific version, i.e. OS X 10.9 Mavericks, Windows 7
        in: query
        required: false
        schema:
          type: string
      - name: os_family
        description: Filter by kind of OS used without specific version, i.e. OS X, Windows
        in: query
        required: false
        schema:
          type: string
      - name: os_company
        description: Filter by company which produced the OS, i.e. Apple Computer, Inc., Microsoft Corporation
        in: query
        required: false
        schema:
          type: string
      - name: platform
        description: Filter by platform, i.e. webmail, desktop, mobile
        in: query
        required: false
        schema:
          type: string
      - name: country
        description: Filter by country messages were opened in, i.e. Denmark, Russia
        in: query
        required: false
        schema:
          type: string
      - name: region
        description: Filter by full name of region messages were opened in, i.e. Moscow, New York
        in: query
        required: false
        schema:
          type: string
      - name: city
        description: Filter by full name of region messages were opened in, i.e. Moscow, New York
        in: query
        required: false
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageClickSearchResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
  /messages/outbound/clicks/{messageid}:
    get:
      operationId: getClicksForSingleOutboundMessage
      tags:
      - Messages API
      summary: Postmark Retrieve Message Clicks
      parameters:
      - name: X-Postmark-Server-Token
        required: true
        description: The token associated with the Server on which this request will operate.
        in: header
        schema:
          type: string
      - name: messageid
        description: The ID of the Outbound Message for which click statistics should be retrieved.
        in: path
        required: true
        schema:
          type: string
      - name: count
        in: query
        description: Number of message clicks to return per request. Max 500.
        required: true
        schema:
          type: integer
          default: 1
          maximum: 500
          minimum: 1
      - name: offset
        in: query
        description: Number of messages to skip.
        required: true
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageClickSearchResponse'
        422:
          $ref: '#/components/responses/422'
        500:
          $ref: '#/components/responses/500'
components:
  schemas:
    OutboundMessageDetail:
      description: ''
      properties:
        Tag:
          type: string
        MessageID:
          type: string
        To:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        Cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        Bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        Recipients:
          type: array
          items:
            type: string
        ReceivedAt:
          type: string
          format: date-time
        From:
          type: string
        Subject:
          type: string
        Attachments:
          $ref: '#/components/schemas/AttachmentCollection'
        Status:
          type: string
        TrackOpens:
          type: boolean
        TrackLinks:
          type: string
          enum:
          - None
          - HtmlAndText
          - HtmlOnly
          - TextOnly
    MessageHeader:
      description: A single header for an email message.
      properties:
        Name:
          description: The header's name.
          type: string
        Value:
          description: The header's value.
          type: string
    MessageEventDetails:
      description: ''
      properties:
        Recipient:
          type: string
        Type:
          type: string
        ReceivedAt:
          type: string
          format: date-time
        Details:
          properties:
            Summary:
              type: string
            BounceID:
              type: string
            DeliveryMessage:
              type: string
            DestinationServer:
              type: string
            DestinationIP:
              type: string
    MessageClickSearchResponse:
      properties:
        TotalCount:
          type: integer
        Clicks:
          type: array
          items:
            $ref: '#/components/schemas/ExtendedMessageClickEventInformation'
    StandardPostmarkResponse:
      description: A Postmark API error.
      properties:
        ErrorCode:
          type: integer
        Message:
          type: string
    EmailNameAddressPair:
      description: ''
      properties:
        Name:
          type: string
        Email:
          type: string
    OutboundMessageDetailsResponse:
      properties:
        TextBody:
          type: string
        HtmlBody:
          type: string
        Body:
          type: string
        Tag:
          type: string
        MessageID:
          type: string
        To:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        Cc:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        Bcc:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        Recipients:
          type: array
          items:
            type: string
        ReceivedAt:
          type: string
          format: date-time
        From:
          type: string
        Subject:
          type: string
        Attachments:
          $ref: '#/components/schemas/AttachmentCollection'
        Status:
          type: string
        TrackOpens:
          type: boolean
        TrackLinks:
          type: string
          enum:
          - None
          - HtmlAndText
          - HtmlOnly
          - TextOnly
        MessageEvents:
          type: array
          items:
            $ref: '#/components/schemas/MessageEventDetails'
    HeaderCollection:
      type: array
      items:
        $ref: '#/components/schemas/MessageHeader'
    OutboundMessageDumpResponse:
      properties:
        Body:
          description: Raw source of message. If no dump is available this will return an empty string.
          type: string
    ExtendedMessageClickEventInformation:
      description: ''
      properties:
        ClickLocation:
          type: string
        Client:
          description: ''
          properties:
            Name:
              type: string
            Company:
              type: string
            Family:
              type: string
        OS:
          properties:
            Name:
              type: string
            Company:
              type: string
            Family:
              type: string
        Platform:
          type: string
        UserAgent:
          type: string
        OriginalLink:
          type: string
        Geo:
          properties:
            CountryISOCode:
              type: string
            Country:
              type: string
            RegionISOCode:
              type: string
            Region:
              type: string
            City:
              type: string
            Zip:
              type: string
            Coords:
              type: string
            IP:
              type: string
        MessageID:
          type: string
        ReceivedAt:
          type: string
          format: date-time
        Tag:
          type: string
        Recipient:
          type: string
          format: email
    InboundSearchResponse:
      description: ''
      properties:
        TotalCount:
          type: integer
        InboundMessages:
          type: array
          items:
            $ref: '#/components/schemas/InboundMessageDetail'
    InboundMessageDetail:
      description: ''
      properties:
        From:
          type: string
        FromName:
          type: string
        FromFull:
          description: ''
          properties:
            Email:
              type: string
            Name:
              type: string
        To:
          type: string
        ToFull:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        Cc:
          type: string
        CcFull:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        ReplyTo:
          type: string
        OriginalRecipient:
          type: string
        Subject:
          type: string
        Date:
          type: string
        MailboxHash:
          type: string
        Tag:
          type: string
        Attachments:
          $ref: '#/components/schemas/AttachmentCollection'
        MessageID:
          type: string
        Status:
          type: string
    AttachmentCollection:
      type: array
      items:
        $ref: '#/components/schemas/Attachment'
    MessageOpenSearchResponse:
      properties:
        TotalCount:
          type: integer
        Opens:
          type: array
          items:
            $ref: '#/components/schemas/ExtendedMessageOpenEventInformation'
    OutboundSearchResponse:
      description: ''
      properties:
        TotalCount:
          type: integer
        Messages:
          type: array
          items:
            $ref: '#/components/schemas/OutboundMessageDetail'
    ExtendedMessageOpenEventInformation:
      description: ''
      properties:
        FirstOpen:
          type: boolean
        Client:
          description: ''
          properties:
            Name:
              type: string
            Company:
              type: string
            Family:
              type: string
        OS:
          properties:
            Name:
              type: string
            Company:
              type: string
            Family:
              type: string
        Platform:
          type: string
        UserAgent:
          type: string
        Geo:
          properties:
            CountryISOCode:
              type: string
            Country:
              type: string
            RegionISOCode:
              type: string
            Region:
              type: string
            City:
              type: string
            Zip:
              type: string
            Coords:
              type: string
            IP:
              type: string
        MessageID:
          type: string
        ReceivedAt:
          type: string
          format: date-time
        Tag:
          type: string
        Recipient:
          type: string
          format: email
    InboundMessageFullDetailsResponse:
      properties:
        From:
          type: string
        FromName:
          type: string
        FromFull:
          description: ''
          properties:
            Email:
              type: string
            Name:
              type: string
        To:
          type: string
        ToFull:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        Cc:
          type: string
        CcFull:
          type: array
          items:
            $ref: '#/components/schemas/EmailNameAddressPair'
        ReplyTo:
          type: string
        OriginalRecipient:
          type: string
        Subject:
          type: string
        Date:
          type: string
        MailboxHash:
          type: string
        TextBody:
          type: string
        HtmlBody:
          type: string
        Tag:
          type: string
        Headers:
          $ref: '#/components/schemas/HeaderCollection'
        Attachments:
          $ref: '#/components/schemas/AttachmentCollection'
        MessageID:
          type: string
        BlockedReason:
          type: string
        Status:
          type: string
    Attachment:
      description: An attachment for an email message.
      properties:
        Name:
          type: string
        Content:
          type: string
        ContentType:
          type: string
        ContentID:
          type: string