---
title: "Create an agent inbox"
method: POST
path: "/api/v1/inboxes"
tags: ["Agent inboxes"]
---

# Create an agent inbox

`POST /api/v1/inboxes`

## Request

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

A real inbox for an AI agent on one of the workspace's verified domains (a workspace owner/admin's key). Agents don't count as paid seats; each plan includes some. With `createKey`, the answer carries a new agent key (shown once).

## Request body

- object
  - `name` string, required
  - `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).
  - `localPart` string: The part before the @. Made from the name when omitted.
  - `domain` string: A verified domain name or id. The first verified one when omitted.
  - `createKey` union: `true` (or key settings) to also create an agent key, shown once.
    - boolean
    - AgentKeyRequest
      - `name` string
      - `scopes` string[]
      - `expiresInDays` integer: No expiry when omitted.

## Response `201`

Created.

- 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).
  - `key` AgentKey
    - `id` string, required
    - `name` string, required
    - `prefix` string, required: Non-secret leading characters.
    - `scopes` string[], required
    - `inboxId` string, required
    - `createdAt` string, date-time, required
    - `lastUsedAt` string, date-time
    - `expiresAt` string, date-time
    - `revokedAt` string, date-time
    - `secret` string: Only when it was just created: the key itself (`smk_…`). Shown once.

## 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.
- `409`: A request with this Idempotency-Key is still in progress.
- `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)