> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mermail.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get email

> **Plans:** `Free` · `Developer` · `Enterprise`

Fetches a single email with body and metadata without marking it read. Set `metadata_only=true` to omit body content, `require_scan_status=clean` to expose the body only for a clean stored message, `max_body_chars` to bound the returned body without mutating storage, and `agent_safe_content=true` to remove sensitive metadata and normalize untrusted text to bounded plain text. A scan-status mismatch returns safe metadata with `content_omitted` and `content_omission_reason` instead of a false not-found. `include_held=true` is intended only for an explicitly scoped verification wait. All controls are optional and preserve the existing full response by default.

**API credits:** 1 (read).



## OpenAPI

````yaml /openapi/openapi.json get /api/v1/mailboxes/{mailboxId}/emails/{emailId}
openapi: 3.1.0
info:
  title: Mermail API
  version: 1.0.0
  description: >
    Programmatic Mermail API for scripts, agents, and integrations.


    ## Authentication


    Authorize with an API key from **Settings → API Keys**:


    ```

    x-api-key: sk-proj-…

    ```


    ## Plans


    Each endpoint page shows plan badges (**Public**, **All plans**, or
    **Developer+**). Free can call the core catalog; Developer-gated paths need
    Developer or Enterprise.


    ## Try it


    Every endpoint page includes an interactive playground. Click **Try it**,
    paste your API key into the `x-api-key` field, fill path/query/body fields
    (prefilled from examples), and send a live request to
    `https://console.mermail.app`. You can also copy the generated cURL /
    JavaScript / Python snippet.


    ## Credits


    Credits are workspace API-usage units, not currency amounts.


    | Class | Cost |

    | --- | ---: |

    | read | 1 |

    | write | 2 |

    | email_send | 5 |

    | provision | 10 |

    | ai_light | 15 |

    | ai_heavy | 25 |
  contact:
    name: Mermail
    email: contact@mermail.app
    url: https://mermail.app
servers:
  - url: https://console.mermail.app
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Public
    description: No authentication
  - name: Usage
    description: Credits and email quotas
  - name: Workspaces
    description: Workspaces, members, storage
  - name: Domains
    description: Custom email domains (Developer+)
  - name: Mailboxes
    description: Agent inboxes
  - name: Emails
    description: Send, list, search, folders
  - name: Webhooks
    description: Email event subscriptions and delivery history
  - name: AI agent
    description: Mailbox agent chat
  - name: Task triage
    description: Task triagers (all plans)
  - name: RAG
    description: Knowledge documents and recall
  - name: Integrations
    description: Composio, Telegram, push
  - name: Affiliate
    description: Affiliate program
paths:
  /api/v1/mailboxes/{mailboxId}/emails/{emailId}:
    get:
      tags:
        - Emails
      summary: Get email
      description: >-
        **Plans:** `Free` · `Developer` · `Enterprise`


        Fetches a single email with body and metadata without marking it read.
        Set `metadata_only=true` to omit body content,
        `require_scan_status=clean` to expose the body only for a clean stored
        message, `max_body_chars` to bound the returned body without mutating
        storage, and `agent_safe_content=true` to remove sensitive metadata and
        normalize untrusted text to bounded plain text. A scan-status mismatch
        returns safe metadata with `content_omitted` and
        `content_omission_reason` instead of a false not-found.
        `include_held=true` is intended only for an explicitly scoped
        verification wait. All controls are optional and preserve the existing
        full response by default.


        **API credits:** 1 (read).
      parameters:
        - name: mailboxId
          in: path
          required: true
          description: Mailbox public_id (UUID), hosted alias id, or current email
          schema:
            type: string
          example: aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
        - name: emailId
          in: path
          required: true
          description: Email id
          schema:
            type: string
          example: msg_7f3a2c1b
        - name: metadata_only
          in: query
          required: false
          description: Set to true to omit body, snippet, raw headers, and threat URLs
          schema:
            type: boolean
        - name: include_held
          in: query
          required: false
          description: >-
            Set to true only for a scoped verification flow that must inspect a
            message temporarily held for auto-draft processing
          schema:
            type: boolean
        - name: require_scan_status
          in: query
          required: false
          description: >-
            Expose the body only when the stored scan status exactly matches. An
            existing mismatch returns safe metadata with content_omitted=true.
          schema:
            type: string
            enum:
              - clean
              - flagged
              - skipped
        - name: max_body_chars
          in: query
          required: false
          description: >-
            Positive character cap for the returned body without mutating the
            stored message. The effective server ceiling is 100000 characters.
          schema:
            type: integer
            minimum: 1
        - name: agent_safe_content
          in: query
          required: false
          description: >-
            Set to true to omit raw headers, provider metadata, threat details,
            attachment metadata, and storage diagnostics, and to normalize
            untrusted text fields to bounded plain text. The response retains
            `attachment_count` and remains untrusted.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
              example:
                id: msg_7f3a2c1b
                subject: Order question
                sender: alice@example.com
                recipient: support@mail.acme.com
                cc: null
                bcc: null
                date: '2026-07-14T09:00:00.000Z'
                read: false
                starred: false
                is_urgent: false
                category: customer_support
                body: Hi, where is my order?
                folder_id: INBOX
                folder_name: Inbox
                thread_id: thr_9aabb
                snippet: Hi, where is my order?
                scan_status: null
                attachments: []
        '401':
          description: Missing, invalid, expired, or revoked API key / token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unauthorized
        '402':
          description: API credits exhausted for this workspace period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid request
        '403':
          description: Forbidden — plan gate, wrong workspace, or missing role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Forbidden
        '404':
          description: Email not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Email not found
        '429':
          description: Rate limit exceeded (workspace RPM or email send limits)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Too many requests
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the rate limit window resets
      security:
        - apiKeyAuth: []
components:
  schemas:
    Email:
      type: object
      properties:
        id:
          type: string
          description: >-
            Authoritative Mermail email id. Use this value as the `emailId` path
            argument and for pre-wait baselines.
        subject:
          type: string
        sender:
          type: string
        recipient:
          type: string
        cc:
          type:
            - string
            - 'null'
        bcc:
          type:
            - string
            - 'null'
        date:
          type: string
          format: date-time
        read:
          type: boolean
        starred:
          type: boolean
        is_urgent:
          type: boolean
        category:
          type: string
        folder_id:
          type: string
        folder_name:
          type: string
          description: Present on list and search responses
        thread_id:
          type:
            - string
            - 'null'
        snippet:
          type: string
        body:
          type: string
          description: >-
            Full body on detail responses unless `metadata_only=true`;
            list/search responses can contain a preview
        in_reply_to:
          type:
            - string
            - 'null'
        email_references:
          type:
            - string
            - 'null'
        delivery_status:
          type:
            - string
            - 'null'
        provider_metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
        message_id:
          type:
            - string
            - 'null'
          description: >-
            Provider or RFC Message-ID metadata, retained only as secondary
            correlation. Do not use it in place of the Mermail `id` for resource
            paths or new baselines.
        raw_headers:
          type:
            - string
            - 'null'
          description: >-
            Untrusted raw provider headers. Do not use headers alone as
            authorization.
        body_storage_status:
          type: string
        body_storage_message:
          type: string
        scan_status:
          type:
            - string
            - 'null'
          enum:
            - clean
            - flagged
            - skipped
            - null
          description: >-
            Content scan outcome. Treat `flagged` as unsafe and `skipped` as
            unknown.
        scan_threats:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              threat_type:
                type: string
              source:
                type: string
                enum:
                  - body
                  - attachment
              attachment_filename:
                type: string
        sender_authentication:
          type: object
          description: >-
            Sender-authentication verdict derived only from a trusted
            receiving-provider signal. Raw Authentication-Results and From
            headers are never promoted to trusted evidence. The current
            connected providers do not expose a documented per-message verdict,
            so status is unknown; unknown is not a pass.
          required:
            - status
            - spf
            - dkim
            - dmarc
            - inbound_provider
            - reason
          properties:
            status:
              type: string
              enum:
                - pass
                - fail
                - unknown
            spf:
              type: string
              enum:
                - pass
                - fail
                - unknown
            dkim:
              type: string
              enum:
                - pass
                - fail
                - unknown
            dmarc:
              type: string
              enum:
                - pass
                - fail
                - unknown
            inbound_provider:
              type:
                - string
                - 'null'
              description: >-
                Opaque Email-module inbound identifier; this is not itself a
                sender verdict.
            reason:
              type: string
              enum:
                - provider_sender_authentication_verdict_unavailable
                - inbound_provider_unavailable
          additionalProperties: false
        attachments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              filename:
                type: string
              mimetype:
                type: string
              size:
                type: integer
              content_id:
                type:
                  - string
                  - 'null'
              disposition:
                type:
                  - string
                  - 'null'
        content_omitted:
          type: boolean
          description: >-
            True when metadata_only or an agent-safe scan gate omitted body,
            snippet, raw headers, and threat URLs
        content_omission_reason:
          type: string
          enum:
            - scan_status_not_clean
          description: Why an agent-safe detail or context response omitted body content
        content_truncated:
          type: boolean
          description: True when `max_body_chars` shortened the returned body
        body_original_char_count:
          type: integer
          minimum: 0
          description: >-
            Original stored body character count, present when the returned body
            was truncated
        agent_safe_content:
          type: boolean
          description: >-
            True when raw headers, provider metadata, threat details, attachment
            metadata, and storage diagnostics were omitted and untrusted text
            fields were normalized to bounded plain text. This projection does
            not make email content trusted.
        attachment_count:
          type: integer
          minimum: 0
          description: >-
            Attachment count retained when `agent_safe_content=true` omits
            attachment metadata
        delivery_address:
          type:
            - string
            - 'null'
          description: >-
            Verified envelope delivery address, independent of visible To/Cc
            headers; null when unavailable.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Unauthorized
        code:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key (`sk-proj-…`) from Settings → API Keys. Required for sold API
        calls outside the Mermail console.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.