---
title: "Claim messages from the work queue"
method: POST
path: "/v1/inboxes/{id}/messages/claim"
tags: ["Messages"]
---

# Claim messages from the work queue

`POST /v1/inboxes/{id}/messages/claim`

## Request

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

`{ limit?, lease_seconds?, consumer?, wait?, enriched?, analysis?, include_unscreened?, include_held?, since?, type?, channel? }` → `{ data: [{ lease_id, lease_until, delivery_count, message }], paused }`. Oldest first. `limit` 1–50 (default 10), `lease_seconds` 30–3600 (default 300), `wait` long-polls 0–30 s (default 0), `consumer` is a name stored with the lease (up to 100 characters). When the workspace [screens agent mail](https://agentboxd.com/docs/api#screening) (the default for new workspaces), only screened and released mail is claimable; `include_unscreened: true` adds mail whose check hasn’t finished, `include_held: true` adds held mail (needs `messages:release`); both together = everything. `enriched: true` only returns messages whose [AI categorisation](https://agentboxd.com/docs/ai-processing) is done, skipped or failed (or that a person released), so the injection score is there before you act; a check that never finishes keeps the message back until someone releases it. `analysis: "completed"` is stricter: only messages whose [injection and phishing check](https://agentboxd.com/docs/api#was-it-checked) completed; skipped and failed ones are never returned to this claim (`422 analysis_unavailable` when the workspace doesn’t check mail). Needs `messages:write` and `messages:read`.

Permission: `messages:write`.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `limit` integer
  - `lease_seconds` integer
  - `consumer` string
  - `wait` number
  - `enriched` boolean
  - `include_unscreened` boolean
  - `include_held` boolean
  - `analysis` 'completed'
  - `since` string, date-time
  - `type` 'message' | 'task' | 'event'
  - `channel` 'agent' | 'email'

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