openapi.yml

openapi: 3.0.0
info:
  version: 1.0.6
  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
    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}/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}/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
      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-domains':
    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: ListTopPublicDomains
      tags:
        - messageStats
      security:
        - APIKeyQueryParam: [ ]
        - APIKeyHeader: [ ]
      summary: List top public domains receiving disposable messages
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    description: 'domain other than mailsac.com'
                    type: string
                    format: domain
                  n:
                    description: 'count of messages'
                    type: integer

        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/mailstats/blacklist':
    get:
      operationId: Denylist
      tags:
        - messageStats
      summary: List the current deny-list
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  '/mailstats/blacklist/{domainOrIP}':
    parameters:
      - name: domainOrIP
        in: path
        required: true
        example: 'gmail.com'
        schema:
          type: string
    get:
      operationId: CheckDenylist
      tags:
        - messageStats
      summary: Check IP or domain on deny-list
      description: Check whether an IP or domain is currently on the deny-list.
      security:
        - APIKeyQueryParam: []
        - APIKeyHeader: []
      responses:
        '200':
          description: 'Single property indicating deny-list status'
          content:
            application/json:
              schema:
                type: object
                properties:
                  blacklisted:
                    type: boolean
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  '/custom_web_sockets':
    parameters:
      - name: key
        in: query
        schema:
          type: string
        description: 'Mailsac-Key in the `?key=` querystring'
      - name: addresses
        in: query
        schema:
          type: string
        description: 'Enhanced addresses or domains which are enabled for web socket messages'
        example: 'anything_123@mailsac.com,mail.mydomain.com'
    post:
      operationId: _doNotUse_WebSocketDocsOnly
      tags:
        - Web Sockets
      summary: Connect a web socket to wss://sock.mailsac.com/incoming-messages
      description: |
        *Note: this does not work in Swagger UI. Visit https://sock.mailsac.com to test.*

        You can receive email via web socket for private email addresses and custom domains.

        To enable web socket forwarding:

        * Addresses: Select *Edit* for the email address you want to forward.
        Then check the checkbox for web socket forwarding, and save.
        * Custom Domains: Select *Manage* for the domain and click the *Forwarding* tab. Toggle
        the *Enable Web Sockets* option.

        Note: Web socket forwarding is **not enabled by default.**

        ### Web Socket Examples

        #### Web Socket Test Page

        https://sock.mailsac.com

        Receive emails in your web browser.

        Experiment with the web socket gateway in realtime.

        #### Web Socket Node.js

        Listen for Mailsac emails via websocket in this tiny Node.js example app.

        https://github.com/ruffrey/mailsac-node-websocket-example

        ### Web Socket Connection Endpoint

        The web socket endpoint is `wss://sock.mailsac.com/incoming-messages`

        Example:

        > wss://sock.mailsac.com/incoming-messages?key=k_e9bPnd2adexample&addresses=jeff@mailsac.com,asdf-outbound.mailsac.com

        > First frame:

        ```
        {
          "status": 200,
          "msg": "Listening",
          "addresses": [
            "jeff@mailsac.com"
          ],
          "domains": [
            "asdf-outbound.mailsac.com"
          ]
        }
        ```

        All web socket messages are JSON. After parsing the JSON, there will be a status field with
        an HTTP status code (usually 200).

        An email coming over the web socket will also have an email property, and its value will be
        the same as the messages REST API, plus some additional fields.

      responses:
        101:
          description: Successful web socket upgrade
          content:
            application/json:
              example:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  msg:
                    type: string
                    example: listening
                  addresses:
                    type: array
                    items:
                      type: string
                      format: email
                      example: anything_123@mailsac.com
                  domains:
                    type: array
                    items:
                      type: string
                      format: email
                      example: asdf-outbound.mailsac.com
      callbacks:
        emailMessageFrame:
          'wss://sock.mailsac.com/incoming-messages':
            post:
              description: Email message object received by your server
              responses:
                101:
                  description: Web socket duplex response from your server
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/EmailMessageWebSocketFrame'

  '/custom_webhooks':
    post:
      operationId: _doNotUse_WebhookDocsOnly
      tags:
        - Webhooks
      summary: Receive a webhook email message on your server
      description: |
        *Note: this does not work in Swagger UI.*

        Webhook Forwarding is one of several options available for enhanced addresses
        and custom domains (via catch-all addresses enabled under a custom domain).

        Forwarding to a Webhook can be configured by selecting Manage Email Addresses from the
        Dashboard. Select the Settings button next to the email address to manage, then input the
        URL under Forward To Custom Webhook and select Save Settings.

        Troubleshoot webhooks using your account *Audit Logs*.
      responses:
        200:
          description: No responses - webhooks are configured under enhanced addresses.
      callbacks:
        emailMessageWebhook:
          'https://your-server.com/endpoint':
            post:
              description: Email message object received by your server
              responses:
                200:
                  description: Expected response from your server is 200 status code
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/EmailMessageWebhook'

components:
  securitySchemes:
    APIKeyQueryParam:
      type: apiKey
      name: _mailsacKey
      in: query
    APIKeyHeader:
      type: apiKey
      name: Mailsac-Key
      in: header
  responses:
    UnauthorizedError:
      description: 'Not authorized. You may need to log in first.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    MessageNotFound:
      description: 'Message not found by id...'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    OwnedByAnotherUser:
      description: 'Requested email address is owned by another user'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseBody'
    AttachmentMeta:
      description: 'Attachment Metadata'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AttachmentMeta'
    CurrentUserStats:
      description: 'Current User Stats'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CurrentUserStats'
    CurrentUserInfo:
      description: 'Current User Information'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CurrentUserInfo'
    MessageHeaders:
      description: 'Message Headers'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageHeaders'
        text/plain:
          example: |
            Received: ""
            Received: ""
            X-Mailsac-Whitelist: ""
            DKIM-Signature: ""
            Content-Type: ""
            Received: ""
            Received: ""
            From: ""
            To: ""
            Subject: ""
            Message-ID: ""
            List-Unsubscribe: ""
            Date: ""
            MIME-Version: ""
          schema:
            type: string
    EmailAddressAvailability:
      description: 'Object indicating if address is private or not'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmailAddressAvailability'

  parameters:
    DomainString:
      in: path
      name: domain
      description: 'Domain'
      required: true
      schema:
        $ref: '#/components/schemas/DomainString'
    EmailString:
      in: path
      name: email
      description: 'Email address'
      required: true
      schema:
        $ref: '#/components/schemas/EmailString'
    DeleteAddressMessagesFlag:
      in: query
      name: deleteAddressMessages
      required: false
      schema:
        type: boolean
    EmailStringList:
      in: header
      name: emails
      description: 'email addresses'
      schema:
        $ref: '#/components/schemas/EmailStringList'
    messageId:
      in: path
      name: messageId
      description: 'Mailsac-generated globally unique message identifier'
      required: true
      schema:
        $ref: '#/components/schemas/MessageId'
    Since:
      in: query
      name: since
      description: 'Return messages returned after this UTC date'
      required: false
      schema:
        $ref: '#/components/schemas/Date'
    Until:
      in: query
      name: until
      description: 'Return messages returned up to this UTC date'
      required: false
      schema:
        $ref: '#/components/schemas/Date'
    Label:
      in: path
      name: label
      description: 'Label for email message - must be url encoded'
      example: "business%20archive"
      required: true
      schema:
        $ref: '#/components/schemas/MessageLabel'
    MessageFolder:
      in: path
      name: folder
      description: 'Folder for email organization'
      required: true
      schema:
        $ref: '#/components/schemas/MessageFolder'
    readBoolean:
      description: 'Set message read/unread'
      in: path
      name: readBoolean
      required: true
      schema:
        $ref: '#/components/schemas/readBoolean'
    BrowserDownload:
      description: 'Download to browser'
      in: query
      name: download
      required: false
      schema:
        type: integer
        enum:
          - 1
    attachmentIdentifier:
      description: 'Unique identifier of email attachment'
      in: path
      name: attachmentIdentifier
      required: true
      schema:
        $ref: '#/components/schemas/attachmentIdentifier'
    md5sum:
      description: 'md5 sum of an attachment'
      in: path
      name: md5sum
      required: true
      schema:
        $ref: '#/components/schemas/md5sum'
    skip:
      in: query
      name: skip
      required: false
      schema:
        $ref: '#/components/schemas/skip'
    limit:
      in: query
      name: limit
      required: false
      schema:
        $ref: '#/components/schemas/limit'
  schemas:
    ErrorResponseBody:
      type: object
      properties:
        message:
          type: string
        error:
          type: string
        validationErrors:
          type: array
          items:
            type: string
    NotEnoughCreditsResponse:
      type: object
      properties:
        message:
          type: string
          example: 'You must purchase more outgoing messages before you can send'
    TooManyRecipientsResponse:
      type: object
      properties:
        message:
          type: string
          example: 'The to field exceeds the maximum allowed size'
    DomainString:
      type: string
      description: 'domain'
      example: 'example.msdc.co'
    EmailString:
      type: string
      format: email
      description: 'email address'
      example: 'anything_123@mailsac.com'
    EmailStringList:
      format: array
      description: 'email addresses'
      items:
        $ref: '#/components/schemas/EmailString'
      example:
        - 'anything-123@mailsac.com'
        - 'anything-456@example.com'
    EmailAddress:
      type: object
      properties:
        _id:
          type: string
          format: email
          description: >-
            the unique identifier of this email address is the email address
            itself
        info:
          type: string
          description: Allows setting custom information about this email address.
        enabledws:
          type: boolean
          description: >-
            boolean defaulting false indicating whether to publish messages via
            web socket when the user owning this inbox is subscribed
        forward:
          type: string
          format: email
          description: 'email address where messages to this inbox will be forwarded'
        webhook:
          type: string
          format: url
          description: 'URL where messages to this inbox will be forwarded'
        webhookSlack:
          type: string
          format: url
          description: 'Slack webhook endpoint where messages should be published'
        webhookSlackToFrom:
          type: boolean
          description: 'When webhookSlack is set, controls whether the message includes TO and FROM'
        owner:
          type: string
          description: 'Account that owns the address (owns the privacy)'
        encryptedInbox:
          type: string
          format: email
          example: inbox-cf5abefaf492601c5fe0a1563c00b76816145206@mailsac.com
          description: >-
            An alternate email address that will result in the message being
            delivered to this inbox. This is not always present.
        catchAll:
          type: string
          format: domain
          description: Indicates whether this is a catch-all address, and for which domain.
        implicit:
          type: boolean
          default: false
          description: When the user owns the domain but has not reserved the address individually, this field is set to true.
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    EmailAddressList:
      format: array
      description: 'email addresses'
      items:
        $ref: '#/components/schemas/EmailAddress'
    EmailMessage:
      type: object
      properties:
        _id:
          $ref: "#/components/schemas/MessageId"
        from:
          type: array
          description: The FROM sender, this will always have 1 item in the array unless the email was malformed.
          items:
            $ref: '#/components/schemas/EmailRecipient'
        to:
          type: array
          description: The RCPT-TO recipients of the email.
          items:
            $ref: '#/components/schemas/EmailRecipient'
        cc:
          type: array
          description: CarbonCopy recipients of the email.
          items:
            $ref: '#/components/schemas/EmailRecipient'
        bcc:
          type: array
          description: BlindCarbonCopy recipients of the email.
          items:
            $ref: '#/components/schemas/EmailRecipient'
        subject:
          $ref: '#/components/schemas/EmailSubject'
        savedBy:
          type: string
          description: 'Indicates a starred message by your account Account._id. Otherwise `null`.'
        originalInbox:
          type: string
          description: 'Same as inbox unless sent to the encryptedInbox, in which case it would be the encryptedInbox.'
        inbox:
          type: string
          description: 'Email address to which this message belongs.'
          format: email
        domain:
          type: string
          format: domain
          example: example.com
          description: 'hostname domain for the inbox'
        received:
          $ref: '#/components/schemas/Date'
        size:
          type: number
          description: 'Content length in bytes of the original raw email message'
        attachments:
          type: array
          description: '`null` or array of MD5 hashes of attachments. Use the Attachments API to get metadata and download attachments.'
          items:
            $ref: '#/components/schemas/md5sum'
        ip:
          type: string
          description: 'The remote SMTP server that send the mail to the server at `via`'
        via:
          type: string
          description: 'IP address of SMTP server that received the message from `ip`'
        folder:
          type: string
          description: 'Inbox folder that this message has been put into'
          default: inbox
          enum:
            - inbox
            - all
            - sent
            - spam
            - trash
        labels:
          type: array
          items:
            type: string
          description: 'Custom inbox labels created by the end user'
        read:
          type: boolean
          description: 'Read/uread status. true=read, false=unread. Only set from the Inbox UI app.'
        rtls:
          type: boolean
          description: 'When true, indicates the SMTP message was received over TLS (encrypted).'
        links:
          type: array
          items:
            type: string
          description: 'List of any URLs that were found in the text and HTML body of the message.'
        spam:
          type: number
          example: 0.345
          description: >-
            Experimental - result of spam filter scan, between 0.0 and 1.0, where 1.0 indicates
            a high likelihood of being spam
    EmailMessageBodyProps:
      type: object
      properties:
        text:
          type: string
          description: Plain text email body
        body:
          type: string
          description: HTML email body
        raw:
          type: string
          description: Entire SMTP original message including headers and attachments
        headers:
          type: object
          description: 'Key-value pairs of headers where the value is an array of strings'
    EmailMessageWebSocketFrame:
      description: Entire email message plus parsed body and raw SMTP
      type: object
      properties:
        status:
          type: integer
          example: 200
        email:
          allOf:
            - $ref: '#/components/schemas/EmailMessageBodyProps'
            - $ref: '#/components/schemas/EmailMessage'
    EmailMessageWebhook:
      allOf:
        - $ref: '#/components/schemas/EmailMessageBodyProps'
        - $ref: '#/components/schemas/EmailMessage'
    EmailMessageList:
      type: array
      description: 'List of full email message objects'
      items:
        $ref: '#/components/schemas/EmailMessage'
    EmailMessageListShort:
      type: array
      description: 'List of condensed email message objects'
      items:
          $ref: '#/components/schemas/EmailMessageShort'
    EmailMessageShort:
      type: object
      properties:
        inbox:
          $ref: '#/components/schemas/EmailMessage/properties/inbox'
        to:
          $ref: '#/components/schemas/EmailMessage/properties/to'
        from:
          $ref: '#/components/schemas/EmailMessage/properties/from'
        subject:
          $ref: '#/components/schemas/EmailMessage/properties/subject'
        originalInbox:
          $ref: '#/components/schemas/EmailMessage/properties/originalInbox'
        size:
          $ref: '#/components/schemas/EmailMessage/properties/size'
        attachments:
          $ref: '#/components/schemas/EmailMessage/properties/attachments'
        received:
          $ref: '#/components/schemas/EmailMessage/properties/received'
        bcc:
          $ref: '#/components/schemas/EmailMessage/properties/bcc'
        cc:
          $ref: '#/components/schemas/EmailMessage/properties/cc'
        domain:
          $ref: '#/components/schemas/EmailMessage/properties/domain'
        folder:
          $ref: '#/components/schemas/EmailMessage/properties/folder'
        ip:
          $ref: '#/components/schemas/EmailMessage/properties/ip'
        labels:
          $ref: '#/components/schemas/EmailMessage/properties/labels'
        links:
          $ref: '#/components/schemas/EmailMessage/properties/links'
        read:
          $ref: '#/components/schemas/EmailMessage/properties/read'
        rtls:
          $ref: '#/components/schemas/EmailMessage/properties/rtls'
        savedBy:
          $ref: '#/components/schemas/EmailMessage/properties/savedBy'
        spam:
          $ref: '#/components/schemas/EmailMessage/properties/spam'
        via:
          $ref: '#/components/schemas/EmailMessage/properties/via'
    DomainsList:
      type: array
      description: 'List of custom domain objects'
      items:
        $ref: '#/components/schemas/Domain'
    Domain:
      type: object
      description: 'Custom domain'
      properties:
        _id:
          type: string
          format: domain
          description: 'domain'
        created:
          type: string
          format: date-time
          description: 'Date domain was created'
        updated:
          type: string
          format: date-time
          description: 'Date domain settings were last updated'
        enablews:
          type: boolean
          description: |
            boolean defaulting false indicating whether to publish messages via
            web socket to any subscribed web socket sessions
        hosted:
          type: boolean
          description: boolean defaulting false indicating whether this is managed by mailsac (on msdc.co)
        isDefault:
          type: boolean
          description: |
            boolean defaulting false indicating whether this is the default
            domain for the account which will show in the sidebar first
        isPrivate:
          type: boolean
          description: |
            boolean defaulting true indicating whether inboxes and messages for this domain will be visible publicly
        lastVerificationErrors:
          type: string
          description: during custom domain verification, this field indicates dns issues
        owner:
          type: string
          description: the account to which this domain is assigned and can be managed
        verificationTxt:
          type: string
          description: |
            during custom domain verification, this field indicates value of a TXT record that must be added to the domain's DNS settings
        verified:
          type: boolean
          description: |
            boolean defaulting false indicating whether this domain has been verified via dns TXT record verificationTxt
        verifiedMx:
            type: boolean
            description: |
                boolean defaulting false indicating whether the domain will receive email successfully at Mailsac. Tthis domain has been verified via dns MX records when true.
    EmailRecipient:
      type: object
      properties:
        name:
          type: string
          description: >-
            friendly email name, optional part of transport so may be empty
            string
        address:
          type: string
          description: email address
    UpdatePrivateAddressForwarding:
      description: 'body object to update address forwarding'
      properties:
        info:
          type: string
          description: 'User configurable metadata about this enhanced private address.'
        forward:
          type: string
          description: >-
            email address - SMTP forwarding / standard email forwarding - set to
            "" or null to disable forwarding
          default: ''
        enablews:
          type: boolean
          description: >-
            boolean, defaults false - set to true to enable web socket
            forwarding (see Web Socket API)
          default: false
        webhook:
          description: >-
            url - set to your public webhook endpoint to receive mail via
            webhook - set to "" or null to disable webhooks
          type: string
          default: ''
        webhookSlack:
          description: >-
            Slack webhook URL where messages will be published.
          type: string
          default: ''
        webhookSlackToFrom:
          type: boolean
          description: 'When webhookSlack is set, controls whether the message includes TO and FROM'
    EmailAddressIntegrity:
      type: object
      required: [email, validFormat]
      properties:
        email:
          type: string
          format: email
          example: billy.wilson@example.com
          description: 'Full email address that was checked.'
        validFormat:
          type: boolean
          description: 'Indicates if the format is valid.'
        local:
          type: string
          example: billy.wilson
          description: 'The "local part" of the email address, before the @ symbol.'
        domain:
          type: string
          format: domain
          example: example.com
          description: >-
            The domain of the email address which was used for evaluating
            disposable components, after the @ symbol.
        isDisposable:
          type: boolean
          description: >-
            Boolean indicating if this email address is known to resolve to
            disposable email providers, most likely making it not useful for
            marketing mailing lists or signups.
        disposableDomains:
          type: array
          format: domain
          example: ["example.com", "others.org"]
          items:
            type: string
          description: >-
            Array of string domains where this email resolves to, which is
            helpful when the domain is custom, but receives its mail at a
            disposable email provider.
        aliases:
          type: array
          example: ["example.com", "192.168.0.1", "example.io"]
          items:
            type: string
            format: domain
          description: >-
            Array of string domains and IP addresses which are associated with
            the domain for this email address.
    EmailSubject:
      type: string
      description: 'Email subject header line. Can be an empty string.'
    EmailAddressIntegrityList:
      type: array
      items:
        $ref: '#/components/schemas/EmailAddressIntegrity'
    EmailAddressAvailability:
      type: object
      description: 'Returns object showing email address availability'
      properties:
        available:
          type: boolean
          description: 'Indicates if the address is available to be reserved'
        email:
          type: string
          format: email
          description: 'email address'
        owned:
          type: boolean
          description: 'Indicates if the address is owned by an account, but not by whom.'
    MessageId:
      type: string
      format: string
      description: 'Unique Mailsac-generated identifier for an email message'
      example: 'm3phnJ2ag3example-0'
    Date:
      type: string
      description: 'Date in ISO 8601'
      format: date
      example: '1985-04-12T23:20:50.52Z'
    MessageLabel:
      type: string
      description: 'Label for email message'
    MessageLabels:
      type: array
      description: 'Labels for an email message'
      items:
        $ref: '#/components/schemas/MessageLabel'
    MessageFolder:
      type: string
      description: 'Folders for a email messages'
      enum:
        - inbox
        - all
        - sent
        - spam
        - trash
        - drafts
    readBoolean:
      type: boolean
      description: >-
        True to mark message as read, False to mark message unread. Default
        False
    MessageHeaders:
      oneOf:
        - type: object
          description: 'SMTP headers are returned as json with header values grouped.'
          example: { "dkim-signature": [""], "received": ["", ""], "date": [""] }
          additionalProperties:
            type: array
            items:
              type: string
        - type: object
          description: 'SMTP headers are returned as JSON maintaining their original order.'
          example: [{ "name": "dkim-signature", "value": "" }, { "name": "received", "value": "" }, { "name": "received", "value": "" }]
          additionalProperties:
            type: object
            properties:
              name:
                type: string
              value:
                type: string

    EmailAttachment:
      type: object
      description: 'Email attachment object'
      properties:
        cid:
          type: string
          description: contentid
        contentDisposition:
          type: string
        encoding:
          $ref: '#/components/schemas/ByteEncoding'
        filename:
          type: string
    EmailAttachmentList:
      type: array
      description: 'Array of Email Attachment Objects'
      items:
        $ref: '#/components/schemas/EmailAttachment'
    ByteEncoding:
      type: string
      enum:
        - byte
        - base64
    SendMessage:
      type: object
      description: 'JSON formatted email message used for sending'
      properties:
        to:
          $ref: '#/components/schemas/SendMessageTo'
        from:
          $ref: '#/components/schemas/SendMessageFrom'
        subject:
          $ref: '#/components/schemas/EmailSubject'
        text:
          type: string
          description: plaintext email contents
        html:
          type: string
          description: html email contents
        attachments:
          $ref: '#/components/schemas/EmailAttachmentList'
        received:
          type: array
          items:
            $ref: '#/components/schemas/ReceivedHeadersList'
        raw:
          description: 'raw SMTP messsage overrides all other properties'
          type: string
      required:
        - to
        - from
        - subject
        - text
        - html
    ReceivedHeaders:
      type: string
      description: 'SMTP Received headers'
    ReceivedHeadersList:
      type: array
      description: 'Array of strings of current and possibly previous received headers'
      items:
        $ref: '#/components/schemas/ReceivedHeaders'
    SendMessageTo:
      description: 'To addresses for SendMessage Object'
      oneOf:
        - $ref: '#/components/schemas/EmailString'
        - $ref: '#/components/schemas/EmailStringList'
    SendMessageFrom:
      description: 'To addresses for SendMessage Object'
      oneOf:
        - $ref: '#/components/schemas/EmailString'
        - $ref: '#/components/schemas/EmailStringList'
    CurrentUserInfo:
      description: 'Information regarding the current user'
      type: object
      properties:
        _id:
          type: string
          description: username
          example: 'my_username'
        email:
          $ref: '#/components/schemas/EmailString'
        invoiceEmail:
          $ref: '#/components/schemas/EmailString'
        capturePrivate:
          type: boolean
          description: Setting which will apply a star to all captured emails.
        messageLimit:
          type: integer
          description: 'Maximum allowed message history (starred messages + all messages on enhanced addresses and domains)'
          example: 1000
        sendsRemaining:
          type: integer
          description: 'Number of outbound recipients left to be able to send a message to'
          example: 8181
        privateDomain:
          type: integer
          description: 'Number of custom domain that the account is entitled to but has not yet reserved'
        privateAddressCredits:
          type: integer
          description: 'Number of enhanced addresses that the account is entitled to but has not yet reserved'
          example: 100
        whitelistAccess:
          type: integer
          description: 'Flag indicating whether account is allowed to request adding IPs to the global allow-list.'
          enum:
            - 0
            - 1
        moAPICount:
          type: integer
          description: 'Approximate number of total API calls made by the account this month'
        apiMonthlyLimit:
          type: integer
          description: 'Number of API calls allowed monthly'
        billingHold:
          type: string
          description: 'When present, indicates the account has past-due invoices and service is disabled'
        disabled:
          type: string
          description: 'When present, indicates a disabled account'
        recents:
          type: array
          description: 'The most recent email addresses viewed by this account in the UI'
          items:
            $ref: '#/components/schemas/EmailString'
        labels:
          description: 'Inbox labels created by the account'
          type: array
          items:
            type: string
        company:
          type: string
          description: 'Company name associated with account'
        address:
          type: string
          description: 'Company address associated with account'
        firehose:
          type: integer
          description: 'Entitlement flag indicating whether the account has access to the Firehose Web Socket API'
        allowPublicDomains:
          type: integer
          description: 'Entitlement flag indicating whether the account has access to Public Domains'
          enum:
            - 0
            - 1
        viewAnalytics:
          type: integer
          description: 'Flag indicating whether account is allowed to view analytics'
          enum:
            - 0
            - 1
        apiAccess:
          type: integer
          description: 'Flag indicating whether account has access to API'
          enum:
            - 0
            - 1
        wsDomain:
          type: integer
          enum:
            - 0
            - 1
        manyKeys:
          type: integer
          enum:
            - 0
            - 1
        internalUnlimited:
          type: integer
          enum:
            - 0
            - 1
        totalSent:
          type: integer
        lastLogin:
          $ref: '#/components/schemas/Date'
        allowMultipleUsers:
          type: integer
          enum:
            - 0
            - 1
        userLimit:
          type: integer
          description: 'Number of users '
        disableSpam:
          type: boolean
        stripeId:
          type: string
        moAPIDisabled:
          type: integer
        moAPILimitWarningEmail:
          type: integer
        apiKeyName:
          type: string
    CurrentUserStats:
      description: 'Describes current user stats'
      type: object
      properties:
        addresses:
          description: 'List of owned email addresses'
          type: array
          items:
            $ref: '#/components/schemas/EmailString'
        domains:
          type: array
          description: 'List of custom domains'
          items:
            type: string
            format: domain
        starredMessages:
          type: integer
          minimum: 0
          example: 100
          description: 'Total count of saved messages'
        storedMessages:
          type: integer
          minimum: 0
          example: 100
          description: 'Total messages on all enhanced addresses and custom domains'
        inboxBytes:
          type: integer
          minimum: 0
          example: 1024
          description: 'Sum size of all messages on enhanced addresses and custom domains'
        totalSent:
          type: integer
          minimum: 0
          example: 100
          description: 'Count of all outgoing messages ever sent'
        lastMonthOps:
          type: integer
          description: 'Count of paid ops performed in the previous month'
        defaultDomain:
          type: string
          description: 'Domain set to default'
    AttachmentMeta:
      description: 'Describes metadata for attachment'
      type: object
      properties:
        checksum:
          $ref: '#/components/schemas/md5sum'
        contentDisposition:
          type: string
          description: 'TODO: describe'
        contentId:
          $ref: '#/components/schemas/attachmentIdentifier'
        contentType:
          type: string
          description: 'Content type of the attachment'
          example: 'application/PDF'
        fileName:
          type: string
          description: 'Filename of attachment'
          example: 'w2.pdf'
        length:
          type: integer
          minimum: 0
          description: 'length of attachment'
          example: 42532
        transferEncoding:
          type: string
          description: 'Encoding used for attachment'
          example: 'base64'
    attachmentIdentifier:
      description: 'Unique identifier for message attachment. Can be the md5sum, smtp content-id (cid), or filename.'
      type: string
      example: '5ea9c924627e68f988c9c7ca44340892 || foo4*foo1@bar.net || horse.png'
    commonAttachments:
      description: 'Common attachments received'
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/md5sum'
        n:
          type: integer
          description: 'Count of public messages with this attachment'
    md5sum:
      description: 'md5 checksum on attachment file'
      type: string
      example: '5ea9c924627e68f988c9c7ca44340892'
      format: md5sum
    skip:
      description: 'How many items to skip (like paging)'
      type: integer
      minimum: 0
      default: 0
    limit:
      description: 'Limit results to this many'
      type: integer
      minimum: 0
      default: 20
      maximum: 1000