# Work queues (mailboxes)

> Work queues and inboxes (mailboxes), and settling the messages delivered from them.

Source: https://docs.getrunstate.com/api/work-queues/

<!-- Generated by apps/docs/scripts/gen-api.mjs from packages/contracts/openapi.yaml. Do not edit. -->

All paths are relative to the API base URL (`https://api.getrunstate.com`) and require `Authorization: Bearer <api key>`. See [the API overview](https://docs.getrunstate.com/api/) for authentication, idempotency and the error envelope.

## GET /mailboxes

```http
GET /v1/spaces/{spaceId}/mailboxes
```

Read-only mailbox list for consoles.

- **Key permission:** `coordination_read`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Mailboxes |

```bash
curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"
```

## POST /mailboxes

```http
POST /v1/spaces/{spaceId}/mailboxes
```

Create work mailbox or inbox.

- **Key permission:** `coordination_write`
- **Idempotency-Key header:** required
- **TypeScript SDK:** `rs.mailboxes.ensure()`
- **Python SDK:** `rs.mailboxes.ensure()`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `mode` | string | no | one of `WORK`, `INBOX`; default `"WORK"` |
| `recipientId` | string | no |  |
| `backlogLimit` | integer | no | default `1000` |

**Responses**

| Status | Meaning |
| --- | --- |
| `201` | Created |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>"}'
```

## GET /mailboxes/{id}/messages

```http
GET /v1/spaces/{spaceId}/mailboxes/{id}/messages
```

Read-only message list with optional state filter.

- **Key permission:** `coordination_read`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `id` | string (uuid) | required |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Messages |

```bash
curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes/<id>/messages" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"
```

## POST /mailboxes/{id}/messages

```http
POST /v1/spaces/{spaceId}/mailboxes/{id}/messages
```

Send scoped message (work_key dedup applies)

- **Key permission:** `coordination_write`
- **Idempotency-Key header:** required
- **TypeScript SDK:** `mailbox.send()`
- **Python SDK:** `mailbox.send()`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `id` | string (uuid) | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `scopeId` | string (uuid) | yes |  |
| `payload` | any JSON | yes |  |
| `workKey` | string | no |  |
| `deadline` | string (date-time) | no |  |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Dedup replay of committed send |
| `201` | Message id |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes/<id>/messages" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scopeId":"<run id>","payload":{"example":true}}'
```

## POST /mailboxes/{id}/recv

```http
POST /v1/spaces/{spaceId}/mailboxes/{id}/recv
```

Receive-and-claim next ready message for a scope.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `mailbox.receive(), mailbox.consume()`
- **Python SDK:** `mailbox.receive(), mailbox.consume()`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `id` | string (uuid) | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `scopeId` | string (uuid) | yes |  |
| `holder` | string | yes |  |
| `holderSession` | string | yes |  |
| `leaseSeconds` | integer | no | default `30` |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Message with claim token |
| `204` | No ready message |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/mailboxes/<id>/recv" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scopeId":"<run id>","holder":"worker-1","holderSession":"<session id>"}'
```

## POST /messages/{id}/renew

```http
POST /v1/spaces/{spaceId}/messages/{id}/renew
```

Renew current receive claim.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `delivery.renew() (automatic inside consume)`
- **Python SDK:** `delivery.renew() (automatic inside consume)`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `id` | string (uuid) | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `token` | string | yes |  |
| `leaseSeconds` | integer | no | 5–600; default `30` |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Renewed |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/messages/<id>/renew" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>"}'
```

## POST /messages/{id}/complete

```http
POST /v1/spaces/{spaceId}/messages/{id}/complete
```

Ack plus optional result atomically.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `delivery.complete()`
- **Python SDK:** `delivery.complete()`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `id` | string (uuid) | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `token` | string | yes |  |
| `result` | object | no | Optional. `payload` alone records the task outcome without publishing a result message; `mailboxId` and `scopeId` must be sent together to also publish the result to that mailbox.  |
| `result.mailboxId` | string (uuid) | no |  |
| `result.scopeId` | string (uuid) | no |  |
| `result.payload` | any JSON | no |  |
| `result.workKey` | string | no |  |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | ACKED |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/messages/<id>/complete" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>"}'
```

## POST /messages/{id}/nack

```http
POST /v1/spaces/{spaceId}/messages/{id}/nack
```

Retry or reject current claim.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `delivery.retry() / delivery.reject()`
- **Python SDK:** `delivery.retry() / delivery.reject()`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `id` | string (uuid) | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `token` | string | yes |  |
| `retry` | boolean | yes |  |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | New message state |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/messages/<id>/nack" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>","retry":true}'
```