openapi: 3.0.3
info:
  title: Mailinator API
  x-sidebar-label: Authentication
  description: >-
    OpenAPI 3 definition for the Mailinator API reference. The specification captures the documented message,
    stats, domain, and rule endpoints exposed under api.mailinator.com.
  version: "2026-03-20"
servers:
  - url: https://api.mailinator.com
    description: Production server
security:
  - ApiTokenHeader: []
  - ApiTokenQuery: []
tags:
  - name: Messages
    description: Message retrieval and mailbox management
  - name: Attachments
    description: Attachment and link retrieval
  - name: Webhook
    description: Webhook message injection endpoints
  - name: Domains
    description: Private domain management
  - name: Authenticator
    description: 2FA and TOTP 
  - name: Stats
    description: Team usage statistics
paths:
  /api/v2/domains/{domain}/inboxes:
    get:
      tags:
        - Messages
      operationId: listDomainMessages
      summary: Get all message summaries for a domain
      description: >-
        Returns message summaries for the supplied domain. Use the optional query
        parameters to scope results to an inbox, control pagination, or request
        full message payloads. Per the documentation, omitting the inbox filter
        or setting it to `*` returns messages across the domain.
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxWildcardParam'
        - $ref: '#/components/parameters/SkipParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/DecodeSubjectParam'
        - $ref: '#/components/parameters/CursorParam'
        - $ref: '#/components/parameters/FullParam'
        - $ref: '#/components/parameters/WaitParam'
        - $ref: '#/components/parameters/DeleteOnFetchParam'
      responses:
        "200":
          description: Message summaries retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxMessagesResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      tags:
        - Messages
      operationId: deleteDomainMessages
      summary: Delete all messages for a domain
      description: Deletes every message for the supplied domain.
      parameters:
        - $ref: '#/components/parameters/DomainParam'
      responses:
        "200":
          description: Domain messages deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/inboxes/{inbox}:
    get:
      tags:
        - Messages
      operationId: listInboxMessages
      summary: Get all message summaries for an inbox
      description: >-
        Returns messages for a specific inbox. To fetch SMS messages, provide
        the team-assigned SMS phone number as the inbox value.
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/SkipParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/DecodeSubjectParam'
        - $ref: '#/components/parameters/CursorParam'
        - $ref: '#/components/parameters/FullParam'
        - $ref: '#/components/parameters/WaitParam'
        - $ref: '#/components/parameters/DeleteOnFetchParam'
      responses:
        "200":
          description: Message summaries retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxMessagesResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      tags:
        - Messages
      operationId: deleteInboxMessages
      summary: Delete all messages for an inbox
      description: >-
        Deletes every message for the targeted inbox. Only private
        domains are supported.
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
      responses:
        "200":
          description: Inbox cleared
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/inboxes/{inbox}/messages:
    post:
      tags:
        - Messages
      operationId: postMessage
      summary: Create a message for an inbox
      description: >-
        Posts a JSON-formatted message into the specified private inbox. The
        payload should follow the documented email-like structure to render in
        the Mailinator web interface.
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageToPost'
      responses:
        "200":
          description: Message accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMessageResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/webhook:
    post:
      tags:
        - Webhook
      operationId: postWebhookMessage
      summary: Inject a message using a webhook token
      description: >-
        Injects a message into a private domain using webhook authentication only.
        This endpoint supports these forms:
        - `https://api.mailinator.com/api/v2/domains/{webhook_token}/webhook/`
      security: []
      servers:
        - url: https://api.mailinator.com
          description: API server
      parameters:
        - $ref: '#/components/parameters/WebhookDomainOrTokenParam'
        - $ref: '#/components/parameters/WebhookTokenQueryParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookMessageRequest'
      responses:
        "200":
          description: Webhook message accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMessageResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/webhook/{inbox}:
    post:
      tags:
        - Webhook
      operationId: postWebhookInboxMessage
      summary: Inject a message for an inbox using a webhook token
      description: >-
        Injects a message into a specific inbox using webhook authentication only.
        This endpoint also supports using:
        `https://api.mailinator.com/api/v2/domains/{webhook_token}/webhook/{inbox}`.
      security: []
      servers:
        - url: https://api.mailinator.com
          description: API server (webhook token in path)
      parameters:
        - $ref: '#/components/parameters/WebhookDomainOrTokenParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/WebhookTokenQueryParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookMessageRequest'
      responses:
        "200":
          description: Webhook message accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMessageResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/inboxes/{inbox}/messages/{messageId}:
    get:
      tags:
        - Messages
      operationId: getInboxMessage
      summary: Get a message from an inbox
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/MessageIdParam'
        - $ref: '#/components/parameters/DeleteOnFetchParam'
      responses:
        "200":
          description: Message retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDetail'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      tags:
        - Messages
      operationId: deleteInboxMessage
      summary: Delete a specific message
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Message deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}:
    get:
      tags:
        - Messages
      operationId: getDomainMessage
      summary: Get a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
        - $ref: '#/components/parameters/DeleteOnFetchParam'
      responses:
        "200":
          description: Message retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageDetail'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/summary:
    get:
      tags:
        - Messages
      operationId: getMessageSummary
      summary: Get a summary for a message from a domain
      description: Returns a summary of the message without body content.
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Message summary retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageSummaryOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/text:
    get:
      tags:
        - Messages
      operationId: getMessageText
      summary: Get text content for a message from a domain
      description: >-
        Returns the extracted “real text” content of the message without HTML,
        formatting, or images. The response is a JSON object with a `text`
        field, and the value may include quoted-printable encoded sequences
        (for example `=C2=A0`) depending on source message encoding.
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Message text retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageTextOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/textplain:
    get:
      tags:
        - Messages
      operationId: getMessageTextPlain
      summary: Get text/plain content for a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: text/plain content retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageTextPlainOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/texthtml:
    get:
      tags:
        - Messages
      operationId: getMessageTextHtml
      summary: Get text/html content for a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: text/html content retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageTextHtmlOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/headers:
    get:
      tags:
        - Messages
      operationId: getMessageHeaders
      summary: Get SMTP headers for a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Message headers retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageHeadersOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/inboxes/{inbox}/messages/{messageId}/attachments:
    get:
      tags:
        - Attachments
      operationId: listInboxMessageAttachments
      summary: Get attachments for a message from an inbox
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Attachments listed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/attachments:
    get:
      tags:
        - Attachments
      operationId: listMessageAttachments
      summary: Get attachments for a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Attachments listed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/inboxes/{inbox}/messages/{messageId}/attachments/{attachmentName}:
    get:
      tags:
        - Attachments
      operationId: getInboxMessageAttachment
      summary: Download an attachment from an inbox
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/MessageIdParam'
        - $ref: '#/components/parameters/AttachmentNameParam'
      responses:
        "200":
          description: Attachment retrieved
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/attachments/{attachmentName}:
    get:
      tags:
        - Attachments
      operationId: getMessageAttachment
      summary: Download an attachment from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
        - $ref: '#/components/parameters/AttachmentNameParam'
      responses:
        "200":
          description: Attachment retrieved
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/inboxes/{inbox}/messages/{messageId}/links:
    get:
      tags:
        - Messages
      operationId: listInboxMessageLinks
      summary: Get links in a message from an inbox
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Links listed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageLinksOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/links:
    get:
      tags:
        - Messages
      operationId: listMessageLinks
      summary: Get links in a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Links listed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageLinksOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/linksfull:
    get:
      tags:
        - Messages
      operationId: listMessageLinksFull
      summary: Get link metadata for a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Link metadata returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageLinksFullOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/inboxes/{inbox}/messages/{messageId}/smtplog:
    get:
      tags:
        - Messages
      operationId: getInboxMessageSmtpLog
      summary: Get SMTP log entries for a message from an inbox
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: SMTP log returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageSmtpLogOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/smtplog:
    get:
      tags:
        - Messages
      operationId: getMessageSmtpLog
      summary: Get SMTP log entries for a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: SMTP log returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageSmtpLogOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/inboxes/{inbox}/messages/{messageId}/raw:
    get:
      tags:
        - Messages
      operationId: getInboxMessageRaw
      summary: Get raw RFC 822 payload for a message from an inbox
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Raw message returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageRawOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/messages/{messageId}/raw:
    get:
      tags:
        - Messages
      operationId: getMessageRaw
      summary: Get raw RFC 822 payload for a message from a domain
      parameters:
        - $ref: '#/components/parameters/DomainParam'
        - $ref: '#/components/parameters/MessageIdParam'
      responses:
        "200":
          description: Raw message returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageRawOnly'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/team/stats:
    get:
      tags:
        - Stats
      operationId: getTeamStats
      summary: Get team statistics
      responses:
        "200":
          description: Team statistics retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamStatsResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/team:
    get:
      tags:
        - Stats
      operationId: getTeam
      summary: Get team configuration
      responses:
        "200":
          description: Team information retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/teaminfo:
    get:
      tags:
        - Stats
      operationId: getTeamInfo
      summary: Get team info snapshot
      responses:
        "200":
          description: Team info retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamInfoResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains:
    get:
      tags:
        - Domains
      operationId: listDomains
      summary: Get a list of private domains
      responses:
        "200":
          description: Domains retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainsResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain_name}:
    get:
      tags:
        - Domains
      operationId: getDomain
      summary: Get private domain details
      parameters:
        - $ref: '#/components/parameters/DomainNameParam'
      responses:
        "200":
          description: Domain retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/stream:
    get:
      tags:
        - Messages
      operationId: streamDomainMessages
      summary: Stream all messages from a domain
      description: >-
        Streams all messages near live for the supplied domain. Use the optional query
        parameters to control pagination, throttling, and message handling.
      parameters:
        - $ref: '#/components/parameters/PrivateDomainParam'
        - $ref: '#/components/parameters/FullParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/ThrottleIntervalParam'
        - $ref: '#/components/parameters/DeleteOnFetchParam'
      responses:
        "200":
          description: Message stream retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageSummary'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/domains/{domain}/stream/{inbox}:
    get:
      tags:
        - Messages
      operationId: streamInboxMessages
      summary: Stream all messages from an inbox
      description: >-
        Streams all messages near live for a specific inbox. Use the optional query
        parameters to control pagination, throttling, and message handling.
      parameters:
        - $ref: '#/components/parameters/PrivateDomainParam'
        - $ref: '#/components/parameters/InboxParam'
        - $ref: '#/components/parameters/FullParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/ThrottleIntervalParam'
        - $ref: '#/components/parameters/DeleteOnFetchParam'
      responses:
        "200":
          description: Message stream retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageSummary'
        "500":
          $ref: '#/components/responses/ErrorResponse'
  /api/v2/totp/{totp_secret_key}:
    get:
      tags:
        - Authenticator
      operationId: getInstantTOTPCode
      summary: Get instant TOTP code based on a secret key
      description: >-
        Generates a Time-based One-Time Password (TOTP) code using the provided
        secret key. The generated code can be used for two-factor authentication (2FA)
        during login or other secure operations.
      parameters:
        - name: totp_secret_key
          in: path
          required: true
          description: The secret key used to generate the TOTP code.
          schema:
            type: string
      responses:
        "200":
          description: TOTP code generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TOTPResponse'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v2/authenticators/{authenticator_id}:
    get: 
      tags:
        - Authenticator
      operationId: getStoredAuthenticatorCode
      summary: Get instant TOTP code based on a stored authenticator ID
      description: >-
        Generates a Time-based One-Time Password (TOTP) code using an already saved authenticator. The generated code can be used for two-factor authentication (2FA)
        during login or other secure operations. authenticator_id is case sensitive.
      parameters:
        - name: authenticator_id
          in: path
          required: true
          description: The unique identifier of the authenticator as found in Web Interface.
          schema:
            type: string
      responses:
        "200":
          description: Authenticator status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatorIDResponse'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiTokenHeader:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Provide the team API token in the Authorization header. Example:
        `Authorization: YourTeamAPIToken`.
    ApiTokenQuery:
      type: apiKey
      in: query
      name: token
      description: Provide the team API token as the `token` query parameter.
  parameters:
    DomainParam:
      name: domain
      in: path
      required: true
      description: >-
        Domain scope. Use `public`, `private`, or a specific private domain name
        assigned to the team.
      schema:
        type: string
    PrivateDomainParam:
      name: domain
      in: path
      required: true
      description: >-
        Private domain scope. Provide a team private domain or custom domain.
        The public domain is not supported by streaming endpoints.
      schema:
        type: string
    InboxParam:
      name: inbox
      in: path
      required: true
      description: Inbox identifier. Provide a mailbox name or the team SMS
        phone number (for SMS retrieval). Use `*` to match inbox prefixes where
        supported by the endpoint.
      schema:
        type: string
    InboxWildcardParam:
      name: inbox
      in: query
      required: false
      description: Optional inbox filter. Use `*` to include every inbox in the
        domain.
      schema:
        type: string
        default: "*"
    MessageIdParam:
      name: messageId
      in: path
      required: true
      description: Unique Mailinator message identifier.
      schema:
        type: string
    AttachmentNameParam:
      name: attachmentName
      in: path
      required: true
      description: Attachment name or identifier. The API also accepts an
        attachment id.
      schema:
        type: string
    SkipParam:
      name: skip
      in: query
      required: false
      description: Number of messages to skip from the start of the result set.
      schema:
        type: integer
        minimum: 0
    LimitParam:
      name: limit
      in: query
      required: false
      description: Number of messages to return (1-99 unless `full=true`).
      schema:
        type: integer
        minimum: 1
        maximum: 99
        default: 50
    SortParam:
      name: sort
      in: query
      required: false
      description: Sort order for returned messages.
      schema:
        type: string
        enum:
          - ascending
          - descending
        default: descending
    DecodeSubjectParam:
      name: decode_subject
      in: query
      required: false
      description: Decode MIME-encoded subjects when true.
      schema:
        type: boolean
        default: false
    CursorParam:
      name: cursor
      in: query
      required: false
      description: Cursor token to continue a prior paged request.
      schema:
        type: string
    FullParam:
      name: full
      in: query
      required: false
      description: >-
        When true, returns the full message entity instead of the summary. The
        Mailinator API enforces a limit of 1 when `full=true`.
      schema:
        type: boolean
        default: false
    WaitParam:
      name: wait
      in: query
      required: false
      description: >-
        Optional long-polling interval. The API waits up to the provided
        duration (e.g., `1s`, `2m`) for new messages before returning.
      schema:
        type: string
    DeleteOnFetchParam:
      name: delete
      in: query
      required: false
      description: >-
        Minimum delay before the fetched message is scheduled for deletion (e.g.,
        `1s`, `5m`, `1h`).
      schema:
        type: string
    DomainNameParam:
      name: domain_name
      in: path
      required: true
      description: Private domain name assigned to the team.
      schema:
        type: string
    WebhookDomainOrTokenParam:
      name: domain
      in: path
      required: true
      description: >-
        Webhook domain segment. Provide either the `webhook_token` in this path
        position, or a private domain name when passing the webhook token in
        `whtoken`.
      schema:
        type: string
    WebhookTokenQueryParam:
      name: whtoken
      in: query
      required: false
      description: >-
        Webhook token used with the `api.mailinator.com` form:
        `/api/v2/domains/{domain}/webhook/?whtoken={webhook_token}`.
      schema:
        type: string
    ThrottleIntervalParam:
      name: throttleInterval
      in: query
      required: false
      description: >-
        Throttle interval to control the rate of streaming messages (e.g.,
        `1s`, `5s`, `1m`).
      schema:
        type: string
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    InboxMessagesResponse:
      type: object
      properties:
        domain:
          type: string
        to:
          type: string
          nullable: true
        msgs:
          type: array
          items:
            $ref: '#/components/schemas/MessageSummary'
        cursor:
          type: string
          nullable: true
      additionalProperties: true
    MessageSummary:
      type: object
      properties:
        id:
          type: string
        subject:
          type: string
        from:
          type: string
        origfrom:
          type: string
        to:
          type: string
        time:
          type: integer
          format: int64
        seconds_ago:
          type: integer
        source:
          type: string
      additionalProperties: true
    MessageSummaryOnly:
      type: object
      description: Simplified message summary response wrapper.
      properties:
        summary:
          type: object
          properties:
            subject:
              type: string
            domain:
              type: string
            from:
              type: string
            id:
              type: string
            to:
              type: string
            time:
              type: integer
              format: int64
          required:
            - subject
            - domain
            - from
            - id
            - to
            - time
      required:
        - summary
    MessageDetail:
      allOf:
        - $ref: '#/components/schemas/MessageSummary'
        - type: object
          properties:
            headers:
              $ref: '#/components/schemas/MessageHeadersResponse'
            fromfull:
              type: string
            parts:
              type: array
              items:
                type: object
                additionalProperties: true
            ip:
              type: string
            ttl:
              type: integer
      additionalProperties: true
    MessageHeadersResponse:
      type: object
      description: SMTP and transport headers for a message.
      properties:
        mime-version:
          type: string
        date:
          type: string
        x-gm-gg:
          type: string
        return-path:
          type: string
        subject:
          type: string
        x-google-dkim-signature:
          type: string
        received:
          type: array
          items:
            type: string
          description: Received chain entries in transport order.
        content-transfer-encoding:
          type: string
        x-mailer:
          type: string
        x-received:
          type: string
        message-id:
          type: string
        from:
          type: string
        content-type:
          type: string
        x-gm-message-state:
          type: string
        to:
          type: string
        dkim-signature:
          type: string
      additionalProperties:
        oneOf:
          - type: string
          - type: array
            items:
              type: string
    MessageHeadersOnly:
      type: object
      description: Simplified message headers response wrapper.
      properties:
        headers:
          $ref: '#/components/schemas/MessageHeadersResponse'
      required:
        - headers
    MessageTextOnly:
      type: object
      description: Simplified message text response.
      properties:
        text:
          type: string
          description: >-
            Extracted message text. Depending on message encoding, this value
            can contain quoted-printable artifacts such as `=C2=A0`.
      required:
        - text
    MessageTextPlainOnly:
      type: object
      description: Simplified text/plain response.
      properties:
        text/plain:
          type: string
      required:
        - text/plain
    MessageTextHtmlOnly:
      type: object
      description: Simplified text/html response.
      properties:
        text/html:
          type: string
      required:
        - text/html
    AttachmentListResponse:
      type: object
      properties:
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
      additionalProperties: true
    Attachment:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        contentType:
          type: string
        size:
          type: integer
        downloadUrl:
          type: string
          format: uri
      additionalProperties: true
    MessageLinksOnly:
      type: object
      description: Simplified extracted links response.
      properties:
        links:
          type: array
          items:
            type: string
      required:
        - links
    MessageLinksFullOnly:
      type: object
      description: Simplified extracted links metadata response.
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/MessageLinkDetail'
      required:
        - links
    LinksResponse:
      $ref: '#/components/schemas/MessageLinksOnly'
    LinksFullResponse:
      $ref: '#/components/schemas/MessageLinksFullOnly'
    MessageLinkDetail:
      type: object
      properties:
        link:
          type: string
          format: uri
        text:
          type: string
      required:
        - link
      additionalProperties: true
    MessageSmtpLogOnly:
      type: object
      description: Simplified SMTP log response.
      properties:
        log:
          type: array
          items:
            $ref: '#/components/schemas/MessageSmtpLogEntry'
      required:
        - log
    SmtpLogResponse:
      $ref: '#/components/schemas/MessageSmtpLogOnly'
    MessageSmtpLogEntry:
      type: object
      properties:
        log:
          type: string
        time:
          type: string
        event:
          type: string
      required:
        - log
        - time
        - event
      additionalProperties: true
    MessageRawOnly:
      type: object
      description: Simplified raw message response.
      properties:
        data:
          type: string
      required:
        - data
    DeleteResponse:
      type: object
      properties:
        status:
          type: string
        count:
          type: integer
      required:
        - status
      additionalProperties: true
    MessageToPost:
      type: object
      properties:
        subject:
          type: string
        from:
          type: string
        to:
          type: string
        text:
          type: string
        html:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        parts:
          type: array
          description: Multipart payload segments. Each part follows RFC 822 conventions.
          items:
            type: object
            additionalProperties: true
      required:
        - subject
        - from
      additionalProperties: true
    WebhookMessageRequest:
      type: object
      description: Message payload accepted by webhook injection endpoints.
      properties:
        from:
          type: string
        subject:
          type: string
        to:
          type: string
        text:
          type: string
        html:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
      required:
        - to
      additionalProperties: true
    PostMessageResponse:
      type: object
      properties:
        status:
          type: string
        id:
          type: string
      required:
        - status
        - id
      additionalProperties: true
    TeamStatsResponse:
      type: object
      properties:
        stats:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              retrieved:
                type: object
              sent:
                type: object
    TeamResponse:
      type: object
      properties:
        private_domains:
          type: array
          items:
            type: string
        webhook_tokens:
          type: array
          items:
            type: string
        sms_numbers:
          type: array
          items:
            type: string
        members:
          type: array
          items:
            type: string
        plan_data:
          type: object
        id:
          type: string
        plan:
          type: string
        team_name:
          type: string
        status:
          type: string
        token:
          type: string
    TeamInfoResponse:
      type: object
      properties:
        server_time:
          type: string
        domains:
          type: array
          items:
            type: string
    DomainsResponse:
      type: object
      properties:
        domains:
          type: array
          items:
            $ref: '#/components/schemas/Domain'
    Domain:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
        verified:
          type: boolean
    RuleCreateRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        enabled:
          type: boolean
          default: true
        match:
          type: string
          enum:
            - ANY
            - ALL
            - ALWAYS_MATCH
        priority:
          type: integer
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/RuleCondition'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/RuleAction'
      required:
        - name
        - priority
        - conditions
        - actions
      additionalProperties: false
    Rule:
      allOf:
        - $ref: '#/components/schemas/RuleCreateRequest'
        - type: object
          properties:
            _id:
              type: string
      additionalProperties: true
    RuleCondition:
      type: object
      properties:
        operation:
          type: string
          enum:
            - EQUALS
            - PREFIX
        field:
          type: string
        value:
          type: string
      required:
        - operation
        - field
        - value
      additionalProperties: false
    RuleAction:
      type: object
      properties:
        action:
          type: string
          enum:
            - WEBHOOK
            - DROP
        action_data:
          type: object
          additionalProperties: true
      required:
        - action
        - action_data
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        errors:
          type: array
          items:
            type: string
      additionalProperties: true
    AuthenticatorIDResponse:
      type: object
      properties:
        passcode:
          type: string
          description: The current TOTP code.
        time_step:
          type: integer
          description: The time step in seconds for the TOTP code.
        id: 
          type: string
          description: The authenticator ID.
        futurecodes:
          type: array
          items:
            type: string
          description: The next 5 "future" TOTP codes.
        next_reset_secs:
          type: integer
          description: Seconds until the current TOTP code resets.
    TOTPResponse:
      type: object
      properties:
        passcode:
          type: string
          description: The current TOTP code.
        time_step:
          type: integer
          description: The time step in seconds for the TOTP code.
        futurecodes:
          type: array
          items:
            type: string
          description: The next 5 "future" TOTP codes.
        next_reset_secs:
          type: integer
          description: Seconds until the current TOTP code resets.