---
title: "Wait for the next message"
method: GET
path: "/v1/inboxes/{id}/messages/wait"
tags: ["Messages"]
---

# Wait for the next message

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

## Request

- Base URL: `https://api.agentboxd.com`
- URL: `https://api.agentboxd.com/v1/inboxes/{id}/messages/wait`
- Auth: HTTP bearer

Long-poll. `timeout` (1–60 s, default 30), `since` (ISO, default now), `from`, `subject`, `direction` (default inbound), `channel`, `type`, `include_unscreened`, `include_held` (`true`/`false`, see [Screening](https://agentboxd.com/docs/api#screening)). Returns `{ data: Message | null }`: the oldest message after `since`, or null on timeout. When the workspace screens agent mail, inbound mail is returned once it is screened, never while it is held. `include_unscreened` + `include_held` together = everything.

Permission: `messages:read`.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `timeout` number
- `since` string
- `from` string
- `subject` string
- `direction` 'inbound' | 'outbound'
- `channel` 'agent' | 'email' | 'mixed'
- `type` 'message' | 'task' | 'event'
- `include_unscreened` 'true' | 'false'
- `include_held` 'true' | 'false'

## Response `200`

OK

- object

## Other responses

- `4XX`: Error
- `5XX`: Error

---

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