MailBridgeAPI Receiving API

openapi: 3.2.0
info:
  title: MailBridge Receiving API
  summary: Turn your own mailbox into a secure email API.
  version: 2026-10-20.1
  description: 'MailBridgeAPI connects a mailbox you own to authenticated HTTP endpoints.


    Use the account API key together with a mailbox API key to send email, read incoming messages, search activity and monitor mailbox readiness without distributing SMTP or IMAP passwords across projects.


    Compatible connections include standard SMTP/IMAP, Gmail, Microsoft 365, Yahoo Mail, Zoho Mail and iCloud Mail. Provider capabilities and limits still apply.


    Keep both API keys in server-side environment variables or a secret manager. Never expose them in browser code, public repositories or mobile application bundles.'
  termsOfService: https://mailbridgeapi.com/terms-of-service/
  contact:
    name: MailBridgeAPI Support
    url: https://mailbridgeapi.com/contact/
    email: info@mailbridgeapi.com
  license:
    name: MailBridgeAPI Terms of Service
    url: https://mailbridgeapi.com/terms-of-service/
  x-logo:
    url: https://mailbridgeapi.com/logo-mark.svg
    altText: MailBridgeAPI
servers:
- url: https://api.mailbridgeapi.com
  description: Production API
security:
- AccountKey: []
  MailboxKey: []
tags:
- name: Receiving
  description: Read incoming messages from the mailbox or the normalized received-message API.
paths:
  /getemail/:
    get:
      summary: Read messages directly from an IMAP folder
      description: Opens the configured IMAP connection when the request runs and returns the current messages from the selected folder. This endpoint does not require AI or automatic replies and does not create local received-history records. Use it for live mailbox reads on standard IMAP connections.
      security:
      - AccountKeyQuery: []
        MailboxKeyQuery: []
      parameters:
      - $ref: '#/components/parameters/Folder'
      - $ref: '#/components/parameters/Start'
      responses:
        '200':
          description: Live IMAP messages keyed by UID under `result.emaillist`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyGetEmailResponse'
              example:
                result:
                  error: '0'
                  emaillist:
                    '50123':
                      id: 50123
                      object: Hello%20there
                      body: '%3Cp%3EHello%3C%2Fp%3E'
                      email1: jane@example.com
                      email2: hello@yourcompany.com
                      timestamp: 1760950800
                      date: 20/10/2026 - 09:00:00
                      size: 42
                      attachment: null
                      loop: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Receiving
      operationId: getLiveMailboxMessages
  /email/received/:
    get:
      summary: List received email through the provider-aware API
      description: Returns a consistent paginated response while selecting the source by mailbox provider. Gmail, Microsoft, Zoho and Yahoo OAuth connections are read directly from the provider. Standard SMTP/IMAP and Apple connections return messages already imported into MailBridgeAPI's local received history. For a live standard-IMAP folder read, use GET /getemail/.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: sender
        in: query
        schema:
          type: string
          format: email
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - $ref: '#/components/parameters/IncludeBody'
      responses:
        '200':
          description: Paginated received email response from the provider or local MailBridgeAPI history
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Receiving
      operationId: listReceivedEmail
components:
  parameters:
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: One-based result page.
    IncludeBody:
      name: include_body
      in: query
      schema:
        type: boolean
        default: false
      description: Include message bodies only when needed.
    From:
      name: from
      in: query
      schema:
        type: string
        format: date
      description: Inclusive start date in YYYY-MM-DD format.
    PerPage:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
      description: Number of results per page.
    Start:
      name: start
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
      description: Zero-based IMAP offset. Increase by 30 to retrieve the next group.
    Folder:
      name: mbox
      in: query
      required: true
      schema:
        type: string
        example: INBOX
      description: Mailbox folder name. Use `INBOX` for received email. Other names depend on the provider.
    To:
      name: to
      in: query
      schema:
        type: string
        format: date
      description: Inclusive end date in YYYY-MM-DD format.
  schemas:
    Error:
      type: object
      required:
      - ok
      - error
      - meta
      properties:
        ok:
          const: false
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
          additionalProperties: false
        meta:
          $ref: '#/components/schemas/Meta'
      additionalProperties: false
    Pagination:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
        per_page:
          type: integer
          minimum: 1
        total:
          type: integer
          minimum: 0
        pages:
          type: integer
          minimum: 0
        next_page_token:
          type:
          - string
          - 'null'
    LegacyGetEmailResponse:
      type: object
      required:
      - result
      properties:
        result:
          type: object
          required:
          - error
          - emaillist
          properties:
            error:
              type: string
            emaillist:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/LegacyEmailMessage'
    LegacyEmailMessage:
      type: object
      properties:
        id:
          oneOf:
          - type: integer
          - type: string
        object:
          type: string
          description: URL-encoded subject in the legacy response.
        body:
          type: string
          description: URL-encoded body in the legacy response.
        email1:
          type: string
          format: email
          description: Sender address.
        email2:
          type: string
          format: email
          description: Recipient address.
        timestamp:
          type: integer
        date:
          type: string
        size:
          type: integer
        attachment:
          oneOf:
          - type: string
          - type: 'null'
        loop:
          type: integer
    Meta:
      type: object
      properties:
        request_id:
          type: string
        api_version:
          type: string
        timestamp:
          type: string
          format: date-time
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
  responses:
    ServerError:
      description: The mailbox provider rejected the operation or an internal service error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: The MailBridgeAPI or provider request limit was reached. Do not retry email sends blindly.
      headers:
        Retry-After:
          description: Seconds to wait before retrying when supplied.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The account API key or mailbox API key is missing, invalid, expired or not allowed to access this mailbox.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is missing a required value or contains an invalid parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    AccountKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Account API key. New endpoints also accept the value as an `Authorization: Bearer` token.'
    MailboxKey:
      type: apiKey
      in: header
      name: X-Mailbox-Key
      description: Mailbox API key selecting exactly one configured mailbox.
    AccountKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: Account API key used by legacy-compatible endpoints. Prefer headers for new integrations when supported.
    MailboxKeyQuery:
      type: apiKey
      in: query
      name: apikeybox
      description: Mailbox API key used by legacy-compatible endpoints.
externalDocs:
  description: Interactive documentation, guides and live endpoint tester
  url: https://mailbridgeapi.com/doc/