---
title: "Long-poll for the next message"
method: GET
path: "/v1/mailboxes/{id}/messages/wait"
tags: ["messages"]
---

# Long-poll for the next message

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

## Request

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

## Path parameters

- `id` string, required

## Query parameters

- `since` string, date-time
- `timeout` string

## Response `200`

Success

- object
  - `message` union, required
    - object
      - `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
              - …
            - `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
    - unknown

## 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)
- `503`: Temporarily unavailable

---

[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)