---
title: "List a mailbox's messages"
method: GET
path: "/v1/mailboxes/{id}/messages"
tags: ["messages"]
---

# List a mailbox's messages

`GET /v1/mailboxes/{id}/messages`

## Request

- Base URL: `https://api.replylayer.ai`
- URL: `https://api.replylayer.ai/v1/mailboxes/{id}/messages`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Query parameters

- `before` string
- `compose_held` 'true' | 'false'
- `direction` 'inbound' | 'outbound'
- `has_attachment` 'true' | 'false'
- `include_firewall_blocked` 'true' | 'false'
- `limit` string
- `search` string
- `sender` string
- `since` string, date-time
- `starred` 'true' | 'false'
- `status` string
- `unread` 'true' | 'false'
- `until` string, date-time
- `view` 'summary' | 'verbose'

## Response `200`

Success

- object
  - `messages` object[], required
    - `agent_safety_context` object, nullable
      - `guidance` string, required
      - `instruction_trust` object
        - `match` 'address', required
        - `provenance` 'managed', required
        - `verdict` 'verified_aligned', required
        - `verified_domain` string, nullable, required
        - `version` 'v1', required
      - `untrusted_content` boolean, required
    - `body_preview` string, nullable, required
    - `compose_held_at` string, date-time, nullable
    - `compose_held_decision` 'quarantine' | 'block' | 'require_human_approval' | 'null', nullable
    - `created_at` string, date-time, required
    - `dashboard_url` string, nullable
    - `direction` 'inbound' | 'outbound', required
    - `email_effect` object
      - `effect_status` 'sent' | 'held_for_review' | 'held_infrastructure' | 'blocked', required
      - `releasable` boolean, required
      - `retryable` boolean, required
      - `terminal` boolean, required
    - `firewall_block` object, nullable
      - `envelope_sender` string, nullable
      - `from_address` string, nullable
      - `matched_field` 'envelope' | 'from' | 'null', nullable
      - `matched_list` 'account_blocklist' | 'mailbox_allowlist' | 'null', nullable
      - `matched_pattern` string, nullable
      - `mode` 'blocklist' | 'allowlist', required
      - `reason_code` 'SENDER_BLOCKED' | 'SENDER_NOT_ON_ALLOWLIST', required
    - `has_attachment` boolean
    - `id` string, required
    - `mailbox_name` string, nullable
    - `read_at` string, nullable
    - `recipient` string, required
    - `releasable` boolean
    - `review_causes` string[], nullable
    - `review_expires_at` string, date-time, nullable
    - `review_trigger_source` 'mailbox_policy' | 'scanner' | 'both' | 'null', nullable
    - `scan` object, nullable
      - `categories` object[], required
        - `category` string, required
        - `decision` 'allow' | 'allow_with_warning' | 'quarantine' | 'require_human_approval' | 'block', required
      - `findings` object[], required
        - `agent_instructions` string[]
        - `attachment_filename` string
        - `attachment_index` integer
        - `attachment_policy_action` 'quarantine_message' | 'metadata_only_after_rewrite' | 'derived_text_finding'
        - `category` string, required
        - `decision` 'allow' | 'allow_with_warning' | 'quarantine' | 'require_human_approval' | 'block', required
        - `expires_at` string, date-time
        - `failure_class` 'inference_error' | 'model_judgment'
        - `pii_type` 'ssn' | 'credit_card' | 'phone_number'
        - `reason` string, nullable, required
        - `retryable` boolean
        - `subtype` string
        - `warning` object
          - `affected_urls` string[], required
          - `attribution_text` string, required
          - `attribution_url` string, required
          - `learn_more` object[], required
            - `threat_type` 'MALWARE' | 'SOCIAL_ENGINEERING' | 'UNWANTED_SOFTWARE' | 'SOCIAL_ENGINEERING_EXTENDED_COVERAGE', required
            - `url` string, required
          - `qualified_wording` string, required
      - `verdict` 'clean' | 'warning' | 'review_required' | 'blocked' | 'quarantined', required
    - `sender` string, required
    - `sender_authentication` object, nullable
      - `verdict` 'verified_aligned' | 'authenticated_unaligned' | 'failed' | 'none' | 'error' | 'null', nullable, required
    - `starred` boolean
    - `state` string, required
    - `subaddress_instance_id` string, nullable
    - `subject` string, required
    - `thread_id` string, nullable

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key (code: UNAUTHORIZED)
- `403`: Forbidden (code: MAILBOX_ACCESS_DENIED)
- `404`: Not found
- `429`: Rate limited (code: RATE_LIMITED)
- `500`: Internal error (code: INTERNAL_ERROR)

---

[API](https://skmtc.dev/replylayer/apis/replylayer-api.md) · [All operations](https://skmtc.dev/replylayer/apis/replylayer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/replylayer/apis/replylayer-api/revisions/2cae6fbd127e?raw)