---
title: "Update or pause an agent inbox"
method: PATCH
path: "/api/v1/inboxes/{id}"
tags: ["Agent inboxes"]
---

# Update or pause an agent inbox

`PATCH /api/v1/inboxes/{id}`

## Request

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

Change its settings, or pause/resume it with `status` (`paused` + optional `pauseReason`, or `active`). Its sponsor or an admin; only an admin changes the sponsor or `disclosure`. A pause for complaints or bounces can't be lifted early (409), and the one that waits for a person needs an admin. Agent keys can't change their own rules.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string
  - `description` string
  - `sponsorUserId` string: A person in the workspace (admins only).
  - `sendMode` 'approval' | 'known' | 'open'
  - `inboundMode` 'all' | 'verified' | 'allowlist'
  - `dailySendCap` integer
  - `newRecipientsDailyCap` integer
  - `allowSenders` string[]
  - `blockSenders` string[]
  - `allowRecipients` string[]
  - `disclosure` boolean: End its mail with a line saying an AI agent sent it, for whom (admins only).
  - `status` 'active' | 'paused': `paused` stops its sending; `active` resumes it.
  - `pauseReason` string

## Response `200`

Updated.

- object
  - `inbox` AgentInbox, required
    - `id` string, required: Also its mailbox id: pass it as `mailbox` to the mail endpoints.
    - `address` string, email, required
    - `name` string, required: What the agent is called; it signs its mail with it.
    - `description` string
    - `status` 'active' | 'paused', required
    - `paused` object
      - `reason` string
      - `by` 'system' | 'person'
      - `since` string, date-time
      - `until` string, date-time: Absent: until a person resumes it.
    - `sponsor` object, nullable, required: The person who answers for the agent: approvals and alerts go to them.
      - `id` string
      - `name` string
      - `email` string, email
    - `sendMode` 'approval' | 'known' | 'open', required
    - `inboundMode` 'all' | 'verified' | 'allowlist', required
    - `dailySendCap` integer, required
    - `newRecipientsDailyCap` integer, required
    - `allowSenders` string[], required: Addresses or `@domains` the agent may read in `allowlist` mode.
    - `blockSenders` string[], required: Never shown to the agent.
    - `allowRecipients` string[], required: The agent may write to these without approval.
    - `disclosure` boolean, required: Its mail ends with a line saying an AI agent sent it, for whom.
    - `createdVia` 'app' | 'api' | 'mcp'
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time
    - `pendingApprovals` integer: Emails waiting for a person (people's keys only).

## Other responses

- `400`: The request is malformed.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks the scope (`missing_scope`) or the access (`forbidden`).
- `404`: Not found — or not reachable with this key.
- `422`: Valid JSON the server can't act on (e.g. unverified domain, suppressed recipient, reused Idempotency-Key).
- `429`: Too many requests.

---

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