---
title: "List messages"
method: GET
path: "/v1/inboxes/{id}/messages"
tags: ["Messages"]
---

# List messages

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

## Request

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

Filters: `labels=a,b` (must have all), `is_read`, `direction`, `channel` (`agent`, `email`, `mixed`), `type` (`message`, `task`, `event`), `screening` (`screened`, `pending`, `held`, `released`: received mail in that [screening](https://agentboxd.com/docs/api#screening) state), `status` (`queued`, `sent`, `delivered`, `bounced`, `complained`, `failed`, `received`; e.g. `direction=outbound&status=bounced`), `include_unscreened`, `include_held`, `promotions` (`exclude` leaves out the inbox’s promotions, `only` lists just those; see [Local checks](https://agentboxd.com/docs/api#local-checks)). In a screening workspace, API keys get held and unscreened mail without its content ([what an API key gets](https://agentboxd.com/docs/api#screening-reads)).

Permission: `messages:read`.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `cursor` string
- `limit` integer
- `labels` string
- `is_read` 'true' | 'false'
- `direction` 'inbound' | 'outbound'
- `include_blocked` 'true' | 'false'
- `channel` 'agent' | 'email' | 'mixed'
- `type` 'message' | 'task' | 'event'
- `promotions` 'include' | 'exclude' | 'only'
- `screening` 'screened' | 'pending' | 'held' | 'released'
- `status` 'queued' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'received'
- `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)