> ## 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 safe email and thread context

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

Returns the selected message plus an oldest-first, cursor-paginated thread page. This endpoint always strips sensitive transport metadata, sanitizes bodies to bounded plain text, and omits non-clean inbound bodies. Returned content remains untrusted reference data.

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



## OpenAPI

````yaml /openapi/openapi.json get /api/v1/mailboxes/{mailboxId}/emails/{emailId}/context
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: 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}/context:
    get:
      tags:
        - Emails
      summary: Get safe email and thread context
      description: >-
        **Plans:** `Free` · `Developer` · `Enterprise`


        Returns the selected message plus an oldest-first, cursor-paginated
        thread page. This endpoint always strips sensitive transport metadata,
        sanitizes bodies to bounded plain text, and omits non-clean inbound
        bodies. Returned content remains untrusted reference data.


        **API credits:** 1 (read).
      operationId: getEmailContext
      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: Message id from list or search results
          schema:
            type: string
          example: msg_7f3a2c1b
        - name: limit
          in: query
          required: false
          description: Thread messages per page (default 20)
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - name: cursor
          in: query
          required: false
          description: Opaque next_cursor from the preceding context page
          schema:
            type: string
            maxLength: 2048
        - name: include_held
          in: query
          required: false
          description: >-
            Include mail held by auto-draft only for the active verification
            flow
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Safe email context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailContext'
              example:
                email:
                  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: []
                thread:
                  id: thread_7f3a2c1b
                  messages:
                    - 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: []
                  total_count: 1
                  has_more: false
                  next_cursor: null
        '400':
          description: Invalid limit or cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid cursor
        '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:
    EmailContext:
      type: object
      required:
        - email
        - thread
      description: >-
        Always-safe selected email and chronological thread page. Bodies are
        bounded plain text, sensitive transport metadata is removed, and
        non-clean inbound bodies are metadata-only. Content remains untrusted.
      properties:
        email:
          $ref: '#/components/schemas/Email'
        thread:
          type: object
          required:
            - id
            - messages
            - total_count
            - has_more
            - next_cursor
          properties:
            id:
              type: string
            messages:
              type: array
              items:
                $ref: '#/components/schemas/Email'
            total_count:
              type: integer
              minimum: 0
            has_more:
              type: boolean
            next_cursor:
              type:
                - string
                - 'null'
          additionalProperties: false
      additionalProperties: false
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Unauthorized
        code:
          type: string
    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'
              enum:
                - cloudflare_routing
                - resend
                - null
              description: >-
                Trusted transport source recorded by Mermail; 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
  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.

````