@mailsac/api/openapi.yml

Official Mailsac API client library

openapi: 3.0.0
info:
  version: 1.0.8
  title: mailsac API Specification
  x-logo:
    url: "/img/mailsac-logo-v2.png"
    altText: 'mailsac logo'
  description: |
    ## About the API

    The Mailsac API allows for interacting with Mailsac services, including checking email,
    email validations, setting up forwarding addresses, receiving web socket email messages,
    and sending outbound mail.

    [**Get a free API key**](https://mailsac.com/api-keys)

    Test the Mailsac API online:

    * [**Swagger UI Explorer** →](https://mailsac.com/docs/swagger)

    **Base API Endpoint**:

    * `https://mailsac.com/api/`
    * _All API documentation is relative to this endpoint._

    **OpenAPI Spec**:

    * [Download JSON](https://mailsac.com/openapi.json)
    * [Download YAML](https://mailsac.com/openapi.yml)


    ### Support and Resources

    * [npm Node.js and Browser library - @mailsac/api](https://www.npmjs.com/package/@mailsac/api)
    * [Full Documentation and Guides](https://docs.mailsac.com)
    * [Community Support and Discussion Forums](https://forum.mailsac.com/forums/)
    * [Web socket example in Node.js - ruffrey](https://github.com/ruffrey/mailsac-node-websocket-example)

    Paid Email Support, Pre-Sales
       > support@team.mailsac.com

    [Terms of Service](https://docs.mailsac.com/en/latest/about/terms_of_service.html)

    [Privacy Policy](https://docs.mailsac.com/en/latest/about/privacy_policy.html)

# servers: section will be automatically replaced by backend
servers:
  - url: https://mailsac.com/api
    description: Mailsac API
tags:
  # Authentication section is just at the top of the API, but is not really a tag.
  - name: 'Authentication Guide'
    description: |
      [API keys](https://mailsac.com/api-keys) are used to establish your identity with the Mailsac API.

      Keys can be passed as a header, querystring parameter, or request body json field.

      ### API Key Format

      Example Key:

      > `k_eoj1mn7x5y61w0egs25j6xrv`

      API keys are alphanumeric, cryptographically-random tokens.


      ## Get an API Key

      [All subscription levels, including free accounts, may create API keys.](https://mailsac.com/v2/credentials/keys)
      API keys cannot be managed by other API keys.

      Go to the [Credentials > API Keys & Users](https://mailsac.com/v2/credentials/keys) from the Dashboard to manage your account's API keys.

      ### Multiple Keys

      The Free and Indie tiers allow just one API key. That works fine for an individual developer or QA tester.

      [Some subscription tiers](https://mailasc.com/pricing) can create multiple API keys, and name each one - useful for managing many apps, users, and deployment environments.

      There's no limit on the number of API credentials which can be generated for the tiers allowing more than one to be created.

      ### API Website Logins

      [Some subscription tiers](https://mailasc.com/pricing) also allow API credentials to be used to log into the website user interface.


      ## Auth Option 1: HTTP Header

      Use the API key as a request header named `Mailsac-Key`.

      ```
      HTTP/1.x 200 OK
      GET /api/addresses/test@example.com/messages
      Host: mailsac.com
      Mailsac-Key: k_eoj1mn7x5y61w0egs25j6xrv
      ```

      Check that your API key is working:

      ```bash
      curl --header "Mailsac-Key: k_eoj1mn7x5y61w0egs25j6xrv" https://mailsac.com/api/me
      ```

      which will return a JSON object with your account details.

      ```json
      {
        "_id": "myaccount_name_here",
        "email": "mail@example.com"

        /* more props */
      }
      ```

      ## Auth Option 2: Query String Parameter

      In the query section of the URL (after `?`) add a parameter for `_mailsacKey`.

      ```bash
      curl https://mailsac.com/api/addresses/test@example.com/messages?_mailsacKey=k_eoj1mn7x5y61w0egs25j6xrv
      ```

      Note: this is the least secure option. We recommend using Option 1: HTTP Header.

      ## Auth Option 3: Request JSON Body

      During a POST, PATCH, or PUT request, add a JSON field for `_mailsacKey`.

      ```json
      {
        "_mailsacKey": "k_eoj1mn7x5y61w0egs25j6xrv",

        /* more POST, PUT props etc. */
      }
      ```
  - x-displayName: Email Messages API
    name: Messages
    description: |
      This section of the API deals with email messages. Mailsac parses messages into many formats,
      and can return various bits of metadata, like the sender, recipients, subject, headers, and
      even all the external links.

      #### Permissions and Disposability

      By default, all emails sent to Mailsac are accepted and public. They are recycled regularly unless starred.

      Setting up a _custom domain_ or _private forwarding address_ means only you can see messages sent to it.

      Anyone can make API requests to view messages on a public (non-owned) inbox. Anyone can also delete messages from public inboxes.

      Throttling is frequently an issue on public inboxes. We strongly recommend using a custom domain or private forwarding address.

  - x-displayName: Email Addresses API
    name: Addresses
    description: |
      This section contains APIs for creating and deleting enhanced private addresses, and configuring
      message routing.

      It is not always necessary to create an email address
      using these APIs. Mailsac will accept nearly any email. Creating an email address allows it to
      kept private. Its mail can be automatally routed to another email address, web sockets, webhooks,
      and Slack.

  - x-displayName: Email Validations API
    name: emailValidation
    description: |
      This setion contains APIs to help determine is an email address is a valid format, whether
      it is a disposable address, and the domains or IP addresses it is associated with (in case
      you want to do your own additional lookups or restrictions).

      There are two routes for validating email addresses.

      The GET route is for quickly testing in a web browser, or for testing one email address at a
      time. The GET route will return a JSON object.

      The POST route accepts an array of up to 50 email addresses and will return an array.

  - x-displayName: Domains API
    name: Domains
    description: |
      This section contains APIs for managing custom domains. It is not complete and will be updated
      with more endpoints soon.

  - x-displayName: Email Message Attachments
    name: Attachments
    description: |
      This section contains APIs for finding and downloading email message attachments.

  - x-displayName: User Account API
    name: Account
    description: |
      This section contains APIs related to the current user and account.

  - x-displayName: Email Stats API
    name: messageStats
    description: |
      This section contains APIs for researching public disposable email. It may be most relevant for
      email security researchers.

paths:
  '/addresses':
    get:
      operationId: ListAddresses
      tags:
         - Addresses
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: List all enhanced email addresses
      description: |
        Get an array of enhanced private inbox address objects for the account.

        These addresses must be setup ("reserved") using `POST /api/addresses/:email`, or
        [on the Add Email Address page](https://mailsac.com/private-address).
      responses:
        '200':
          description: List of enhanced address objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddressList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/addresses/{email}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
    get:
      operationId: GetAddress
      tags:
         - Addresses
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: "Fetch an address or check if it is reserved"
      responses:
        '200':
          description: 'Returns an object if owned by the current account, OR is not owned. Includes the `encryptedInbox` field. If not owned, will omit the `owner` key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddress'
        '401':
          description: 'Returns 401 if owned by another account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
    post:
      operationId: CreateAddress
      tags:
         - Addresses
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: 'Reserve (create/own) a private email address'
      description: |
        Sets the email address private and "owned" by the account. All messages which already exist,
        and any future messages which are received, will be private to this account only.

        An email address must be reserved to be able to forward messages to another email address,
        Slack, web sockets, or webhooks. Public email addresses, and private email addresses under
        a custom domain, are not routeable.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePrivateAddressForwarding'
      responses:
        '200':
          description: 'Returns the newly created email address'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddress'
        '400':
          description: 'Already reserved by the current user'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '401':
          description: 'Owned by another account'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
    put:
      operationId: UpdateAddress
      tags:
         - Addresses
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      summary: Update private email address forwarding and metadata
      description: |
        For a private email address, set it to forward to another place.

        It can be forwarded to another email (with `via mailsac` indicator), to a websocket, to a webhook,
        or to a Slack channel.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePrivateAddressForwarding'
      responses:
        '200':
          description: 'email forwarding successfully configured'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    delete:
      operationId: DeleteAddress
      tags:
         - Addresses
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      parameters:
        - $ref: '#/components/parameters/DeleteAddressMessagesFlag'
      summary: 'Release an enhanced email address'
      description: |
        Removes this enhanced private address from ownership by the account. Any email received to the
        address's inbox will be public in the future, unless the address was under a custom domain
        which is set private.
      responses:
        '200':
          description: 'successfully released address'
        '400':
          description: 'Not currently owned by the current account, or already deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '401':
          description: 'Owned by another account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
  '/addresses/{email}/availability':
    parameters:
      - $ref: '#/components/parameters/EmailString'
    get:
      operationId: CheckAvailability
      tags:
         - Addresses
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: 'Check address ownership'
      responses:
        '200':
          $ref: '#/components/responses/EmailAddressAvailability'
  '/private-addresses-bulk':
    post:
      operationId: CreateAddresses
      tags:
        - Addresses
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: 'Reserve multiple enhanced addresses'
      description: |
        Reserves multiple enhanced private addresses. The max addresses per request is 100.

        It is not necessary to create enhanced addresses before receiving email. Enhanced addresses
        are only necessary to forward messages to another email address, Slack, web sockets, webhooks,
        or fetch messages over POP3.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                addresses:
                  $ref: '#/components/schemas/EmailStringList'
      responses:
        '200':
          description: 'Returns the newly created email addresses'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddressList'
        '400':
          description: 'Not enough enhanced address credits'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
        '401':
            $ref: '#/components/responses/UnauthorizedError'
  '/validations/addresses/{email}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
    get:
      operationId: ValidateAddress
      tags:
        - emailValidation
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: Validate an email address and if it is disposable
      description: |
        Determine whether an email address is a valid format, whether it is a disposable address,
        and the domains or IP addresses it is associated with.
      responses:
        '200':
          description: EmailAddressIntegrity object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddressIntegrity'
  '/validations/addresses':
    post:
      operationId: ValidateAddressesBulk
      tags:
        - emailValidation
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: Validate up to 50 email addresses
      description: |
        Determine whether an email address is a valid format, whether it is a disposable address,
        and the domains or IP addresses it is associated with.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  $ref: '#/components/schemas/EmailStringList'
      responses:
        '200':
          description: 'Array of EmailAddressIntegrity objects'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddressIntegrityList'
  '/addresses/{email}/message-count':
    parameters:
      - $ref: '#/components/parameters/EmailString'
    get:
      operationId: CountMessages
      tags:
        - Messages
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      summary: Count messages for an email inbox
      description: >-
        Get the number of messages for an email inbox address.

        **It is NOT necessary to reserve the address** before using this route. Whether it is
        an address on a custom domain, or a public domain, or mailsac.com, the mail can be counted
        as long as nobody else owns it.
      responses:
        '200':
          description: 'Email messages'
          content:
            application/json:
              schema:
                properties:
                  count:
                    type: number
                    example: 3
                  inbox:
                    type: string
                    example: "example@mailsac.com"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/OwnedByAnotherUser'
  '/addresses/{email}/messages':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/Until'
      - $ref: '#/components/parameters/limit'
    get:
      operationId: ListMessages
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: List messages for an email inbox
      description: >-
        Get a list of messages for the email address.
        Messages are always **sorted in decending order by when they were received**, with the newest message
        always in the first position of the array.


        The email message objects are abbreviated to provide basic meta data. To get more information about
        a specific message, use `GET /api/addresses/{email}/messages/{messageId}`.


        **It is NOT necessary to reserve the address** before checking mail! Whether it is
        an address on a custom domain, or a public domain, or mailsac.com, the mail can be checked with
        this route.
      responses:
        '200':
          description: 'Email messages'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailMessageList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/OwnedByAnotherUser'
    delete:
      operationId: DeleteAllMessages
      tags:
        - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: Delete all messages for an email inbox
      description: |
        This deletes all messages for a specific email address.

        The address must be an owned address or an address in a owned domain.
        Starred messages will not be deleted. Use `DELETE /addresses/{email}/messages/{messageId}`
        to remove starred messages or unstar the messages before calling this route.
      responses:
        '204':
          description: 'All non-starred messages deleted'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/addresses/starred/messages':
    get:
      operationId: ListStarredMessages
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: List starred (saved) messages on the account
      description: >-
        Get a list of messages that have been saved and made private for the
        entire account using the "star message" feature.


        Messages recieved via the Capture Service will also show up as starred IF the `capturePrivate`
        flag on the account is enabled.
      responses:
        '200':
          description: 'List of email messages'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailMessageList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/addresses/{email}/messages/{messageId}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
    get:
      operationId: GetMessageMetadata
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: 'Get email message metadata'
      description: |
        Retrieves metadata about a single email message. This route includes additional metadata
        not available when listing messages, such as parsed links from the text or HTML body, and
        attachment md5sums.

        To get even more information about message attachments, like filenames, see the
        Attachments API.

        To get the entire original SMTP message, see the "raw" message route.
      responses:
        '200':
          description: 'Email message full object'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailMessage'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
    delete:
      operationId: DeleteMessage
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: Delete an email message
      description: 'Deletes an individual email message. There is no trash or undo.'
      responses:
        '200':
          description: 'deletes an email message'
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    $ref: '#/components/schemas/MessageId'
                  inbox:
                    $ref: '#/components/schemas/EmailString'
                  message:
                    type: string
                    example: "Message was deleted."
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/raw/{email}/{messageId}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/BrowserDownload'
    get:
      operationId: GetFullRawMessage
      tags:
        - Messages
      summary: Get original SMTP message
      description: |
        Gets the entire original SMTP message transport - everything that was sent over the network
        to Mailsac's inbound servers, plus any Mailsac-generated `Received` headers, and
        special `x-mailsac-*` headers.
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: |
                  Received: from 107.174.77.77 by frontend1-172-31-29-224 via 172.31.99.99 with
                    HTTP id 1xyuM9Oexample for <ab@mailsac.com>; Mon Dec 24 2018 15:23:55 UTC
                  Received: from 107.174.66.66 by smtp-in2-172-31-42-57 via 172.31.88.88 (proxy)
                    with SMTP id 1xyuM9Oexample for <ab@mailsac.com>; Mon, 24 Dec 2018 15:23:55 UTC
                  X-Mailsac-Whitelist: ab@mailsac.com,f@mailsac.com,107.174.234.77
                  DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailsac.com;
                   q=dns/txt; s=mailsacrelay;
                   bh=QK4Dkk9a92aiAvanYe/AQdKO2djgexample=;
                   h=from:subject:to:mime-version:content-type:list-unsubscribe;
                   b=jWPuv7tyPRdH+QBKJdOX5Bxjjy82jaaVPZH5p17prXCoZQXlqg/tbqEiPeU6LiwyWfnWsQZV
                   vpeh1taqZq4EqiM+5tjmF7W/exampleo=
                  Content-Type: multipart/alternative;
                   boundary="----sinikael-?=_1-1545665044444.8772521444444"
                  Received: from frontend2-172-31-99-99 ([54.190.149.200]) with HTTP by
                   cranberry; Mon Dec 24 2018 10:23:46 GMT-0500 (Eastern Standard Time)
                  Received: from ruffrey (f@mailsac.com) ([98.208.22.74]) with HTTP id
                   fe-zi5dp0gwhaa by frontend2-172-31-37-24 ([54.190.149.200]); Mon Dec 24
                   2018 15:23:46 GMT+0000 (Coordinated Universal Time)
                  From: f@mailsac.com
                  To: ab@mailsac.com
                  Subject: test
                  Message-ID: <1rid-zoH3dq3s@mailsac.com>
                  List-Unsubscribe: <mailto:abuse@mailsac.com>
                  Date: Mon, 24 Dec 2018 15:23:54 +0000
                  MIME-Version: 1.0

                  ------sinikael-?=_1-15456650346550.8772521546394454
                  Content-Type: text/plain
                  Content-Transfer-Encoding: 7bit

                  hi testing

                  let's go
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/addresses/{email}/messages/{messageId}/headers':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/BrowserDownload'
    get:
      operationId: GetHeaders
      tags:
        - Messages
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      summary: Get parsed message headers
      description: |
        Returns pre-parsed message headers in one of 3 formats - `json`, `json-ordered`, or `plain`.

        If no querystring parameter is provided, the default format will be `json`.

        Every email is different; fields in the below examples are not guaranteed to exist.

      parameters:
        - name: messageHeadersFormat
          in: query
          required: false
          schema:
            type: string
            enum:
              - json
              - json-ordered
              - plain
      responses:
        '200':
          $ref: '#/components/responses/MessageHeaders'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/dirty/{email}/{messageId}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/BrowserDownload'
    get:
      operationId: GetBodyDirty
      tags:
        - Messages
      summary: Get message HTML body (dirty)
      description: |
        Get a message's HTML content.

        Attached images are inlined and nothing has been stripped.

        When no HTML body was sent in the original message, a simple HTML body will be created.

        Use the querystring param ?download=1 to trigger file download in browser.
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      responses:
        '200':
          description: OK
          content:
            text/html:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/body/{email}/{messageId}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/BrowserDownload'
    get:
      operationId: GetBodySanitized
      tags:
        - Messages
      summary: Get the message HTML body (sanitized)
      description: |
        Get safe HTML from an email message. Scripts, images and links are stripped out. This HTML
        is safer to render than the potentially "dirty" original HTML.

        When no HTML body was sent in the original message, a simple HTML body will be created.

        Use the querystring param ?download=1 to trigger file download in browser.
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      responses:
        '200':
          description: OK
          content:
            text/html:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/text/{email}/{messageId}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/BrowserDownload'
    get:
      operationId: GetBodyPlainText
      tags:
        - Messages
      summary: 'Get message plaintext'
      description: |
        Get a message's text content. If the original message only contained HTML, a simple plain
        text body will be generated.

        HTTP links in the plain text email will be available when fetching the message's metadata
        at the `message.links[]` property.

        Use the querystring param ?download=1 to trigger file download in browser.
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/addresses/{email}/messages/{messageId}/star':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
    put:
      operationId: ToggleMessageStar
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: Star (save) a message
      description: |
        Toggle a message's *starred* status so it will not be automatically recycled when the account's
        message storage limit is reached.

        There is no PUT body.

        It returns only the message metadata.
      responses:
        '200':
          description: 'Toggle starred status to protect from deletion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailMessageShort'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/addresses/{email}/messages/{messageId}/labels/{label}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/Label'
    put:
      operationId: AddMessageLabel
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: Add a label to a message
      description: |
        To help organize messages and group messages together, add a label to a message. Labels
        are used in the Inbox UI to group messages.

        When successful, returns 200 with a subset of the message object.

        When the label already exists on the message, the message is not modified and the API
        endpoint returns 200.

        No PUT body is needed.
      responses:
        '200':
          description: 'Sets the specified label on a message.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    $ref: '#/components/schemas/MessageId'
                  labels:
                    $ref: '#/components/schemas/MessageLabels'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
    delete:
      operationId: DeleteMessageLabel
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: Remove a label from a message
      description: |
        Removes a label from a message. Returns 200 with a subset of the message object when successful.

        When the label did not exists on the message, the message is not modified and the API endpoint returns 200.
      responses:
        '200':
          description: 'Removes the label from a message.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    $ref: '#/components/schemas/MessageId'
                  labels:
                    $ref: '#/components/schemas/MessageLabels'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/MessageNotFound'
  '/addresses/{email}/messages/{messageId}/folder/{folder}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/MessageFolder'
    put:
      operationId: SetMessageFolder
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: 'Move a message into a folder'
      description: |
        Move the message to a different mail folder.

        No new folders can be added. To organize mail, use labels.

        No PUT body is needed.
      responses:
        '200':
          description: 'Moved message to folder'
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    $ref: '#/components/schemas/MessageId'
                  folder:
                    $ref: '#/components/schemas/MessageFolder'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/addresses/{email}/messages/{messageId}/read/{readBoolean}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/readBoolean'
    put:
      operationId: SetMessageReadStatus
      tags:
         - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: 'Set message read/unread status'
      description: |
        Change the read state of a message.

        Pass `readBoolean` as `true` to mark the message as read, and `false` to mark it as unread.
        The default for any new message `false` (unread).

        No PUT body is needed.
      responses:
        '200':
          description: 'Set read/unread status'
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    $ref: '#/components/schemas/MessageId'
                  folder:
                    $ref: '#/components/schemas/readBoolean'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/MessageNotFound'
  '/inbox':
    parameters:
      - $ref: '#/components/parameters/limit'
      - name: since
        in: query
        description: 'Only fetch messages since this date'
        required: false
        schema:
          $ref: '#/components/schemas/Date'
      - $ref: '#/components/parameters/skip'
    get:
      operationId: ListInboxMessages
      tags:
        - Messages
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      summary: Get all account messages paginated
      description: |
        Used by the Inbox UI to display all messages for the account, across all domains and private
        addresses.

        Returns email message short metadata, paginated, with the global account unread message count.
      responses:
        '200':
          description: 'List of short message metadata objects'
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailMessageListShort'
                  unread:
                    type: integer
                  limit:
                    type: integer
                  skip:
                    type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/inbox-filter':
    parameters:
      - name: andSubjectIncludes
        in: query
        description: 'Messages must include this text in the subject line'
        required: false
        schema:
          type: string
      - name: andFrom
        in: query
        description: 'Messages must include this text in FROM envelope'
        required: false
        schema:
          type: string
      - name: andTo
        in: query
        description: 'Messages must include this text in TO envelope or the `message.inbox` is equal to this value'
        required: false
        schema:
          type: string
      - name: andRead
        in: query
        description: 'Messages must be read or unread'
        required: false
        schema:
          type: boolean
    get:
      operationId: FilterInboxMessages
      tags:
        - Messages
      summary: Filter messages in account by to, from, and/or subject
      description: |
        Filter account messages within the the `to` and `from` `.address` fields, and the
        `subject` line. This differs from `/api/inbox-search` by using logical AND, rather than OR
        in `/api/inbox-search`.

        At least one query condition is required, otherwise a 400 will be returned.

        A maximum of 100 results will ever be returned. Refine the query or reduce the number of messages
        in the account to find specific items.
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      responses:
        '200':
          description: 'Query and search results'
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailMessageListShort'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/inbox-search':
    parameters:
      - name: query
        in: query
        description: 'Searches to, from, and subject for all messages on this account, limited to 100 results.'
        required: false
        schema:
          type: string
    get:
      operationId: SearchInboxMessages
      tags:
        - Messages
      summary: Search messages by to, from, and subject
      description: |
        Search all account messages within the the `to` and `from` `.address` fields, and the
        `subject` line. This differs from `/api/inbox-filter` by using logical OR, rather than AND
        in `/api/inbox-filter`.

        A maximum of 100 results will ever be returned. Refine the query or reduce the number of messages
        in the account to find specific items.
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      responses:
        '200':
          description: 'Query and search results'
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailMessageListShort'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/domains':
    get:
      operationId: ListDomains
      tags:
        - Domains
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      summary: List domains
      description: >-
        List custom domains for the account.
      responses:
        '200':
          description: 'Domains list'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainsList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/domains/{domain}':
    get:
        operationId: GetDomain
        tags:
            - Domains
        security:
            - APIKeyQueryParam: [ ]
            - APIKeyHeader: [ ]
        summary: Get domain information
        description: >-
            Get information about a configured domain, including the number of messages.
        responses:
          '200':
            description: 'Domain information'
            content:
                application/json:
                  schema:
                    properties:
                      domain:
                        $ref: '#/components/schemas/Domain'
                      totalMessages:
                        type: integer
                      catchAllAddress:
                        $ref: '#/components/schemas/EmailAddress'
          '401':
            $ref: '#/components/responses/UnauthorizedError'
  '/domains/{domain}/messages':
    parameters:
      - $ref: '#/components/parameters/DomainString'
      - $ref: '#/components/parameters/Until'
      - $ref: '#/components/parameters/limit'
    get:
      operationId: ListDomainMessages
      tags:
        - Messages
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      summary: List messages for an domain
      description: >-
        Get a list of messages across any inboxes
        of a domain. Messages are always **sorted in decending order by when they were received**, with the
        newest message always in the first position of the array.


        The email message objects are abbreviated to provide basic meta data. To get more information about
        a specific message, use `GET /api/addresses/{email}/messages/{messageId}`.


        The domain must be owned by the account making the request, and have DNS validated.

        Paginate with `until?=<Date>` and `limit=<uint>`.
      responses:
        '200':
          description: 'Email messages'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailMessageListShort'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/OwnedByAnotherUser'
  '/domains/:domain/privacy/:isPrivateBoolean':
    parameters:
      - $ref: '#/components/parameters/DomainString'
      - in: path
        name: isPrivateBoolean
        description: 'boolean indicating private or public messages'
        required: true
        schema:
          type: boolean
  '/domains/{domain}/delete-all-domain-mail':
    parameters:
      - $ref: '#/components/parameters/DomainString'
    post:
      operationId: DeleteAllDomainMessages
      tags:
        - Messages
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: 'Delete all messages in a domain'
      description: |
        Delete all messages for a specifc domain. Starred messages will be deleted.

        The domain must be owned domain.
      responses:
        '204':
          description: 'All non-starred messages deleted'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/me':
    get:
      operationId: User
      tags:
        - Account
      summary: 'Get current account'
      description: 'Get information about the account for this API key.'
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          $ref: '#/components/responses/CurrentUserInfo'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/me/stats':
    get:
      operationId: AccountStats
      tags:
        - Account
      summary: 'Get account stats'
      description: 'Get summary information about email addresses, domains, and usage.'
      parameters:
        - name: overrideAccountId
          in: query
          required: false
          schema:
            type: string
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          $ref: '#/components/responses/CurrentUserStats'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/addresses/{email}/messages/{messageId}/attachments':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
    get:
      operationId: ListMessageAttachments
      tags:
        - Attachments
      summary: 'List attachments for an email message'
      description: 'Get attachment metadata on email message.'
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          $ref: '#/components/responses/AttachmentMeta'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/addresses/{email}/messages/{messageId}/attachments/{attachmentIdentifier}':
    parameters:
      - $ref: '#/components/parameters/EmailString'
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/attachmentIdentifier'
    get:
      operationId: DownloadAttachment
      tags:
        - Attachments
      summary: 'Download email attachment'
      description: 'Download an email message attachment as a file.'
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/mailstats/common-attachments':
    parameters:
      - name: startDate
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Date'
      - name: endDate
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Date'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/limit'
    get:
      operationId: ListPublicAttachments
      tags:
        - Attachments
      summary: Search for attachments
      description: |
        Search for attachments that were received during the requested time period. Limited to public
        inboxes and messages not starred by a user.

        Responds with 'Failed to fetch' in swagger editor. Works in curl with generated example.
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/commonAttachments'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/mailstats/common-attachments/{md5sum}/count':
    parameters:
      - $ref: '#/components/parameters/md5sum'
    get:
      operationId: CountPublicAttachments
      summary: 'Count public attachments'
      description: |
        Provides count of attachments by md5 sum

        Responds with 'Failed to fetch' in swagger editor, works in curl with generated example
      tags:
        - Attachments
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  n:
                    type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/mailstats/common-attachments/{md5sum}':
    parameters:
      - $ref: '#/components/parameters/md5sum'
    get:
      operationId: ListMessagesForAttachment
      summary: 'List public messages with an attachment'
      description: 'List the email messages that have attachments with the requested MD5 sum. Limited to non-private inboxes.'
      tags:
        - Attachments
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailMessage'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/mailstats/common-attachments/{md5sum}/download':
    parameters:
      - $ref: '#/components/parameters/md5sum'
    get:
      operationId: DownloadPublicAttachment
      summary: 'Download public attachment'
      description: 'Download an attachment with the MD5 sum requested.'
      tags:
        - Attachments
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/mailstats/top-addresses':
    parameters:
      - name: startDate
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: endDate
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/limit'
    get:
      operationId: ListTopPublicAddresses
      tags:
        - messageStats
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: List top public disposable email addresses receiving messages
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    $ref: '#/components/schemas/EmailString'
                  n:
                    description: 'count of messages'
                    type: integer

        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/mailstats/top-senders':
    parameters:
      - name: startDate
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: endDate
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/limit'
    get:
      operationId: ListTopPublicSenders
      tags:
        - messageStats
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      summary: List top sender email addresses for disposable public messages