---
title: "POST /inboxes"
method: POST
path: "/inboxes"
---

# POST /inboxes

`POST /inboxes`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/inboxes`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Request body

- object: Request body for creating a new inbox
  - `username` string: Local part of the inbox email address (letters, numbers, dots, hyphens, underscores). Normalized to lowercase.
  - `domain` string: Domain for the inbox email address; uses the default domain if omitted
  - `displayName` string: Human-readable display name for the inbox (max 128 characters)
  - `agentId` string: ID of the agent to associate with this inbox. With an agent-scoped key, defaults to the calling agent and may only name that agent; naming a different agent requires a master key. With a master key, omitting it creates a dedicated backing agent for the inbox.

## Response `200`

OK

- object: Inbox resource representation
  - `id` string, required: Unique identifier of the inbox
  - `email` string, email, required: Full email address of the inbox
  - `domain` string, required: Domain portion of the inbox email address
  - `localPart` string, required: Local part (before the @) of the inbox email address
  - `displayName` string, nullable, required: Human-readable display name, or null if not set
  - `agentId` string, required: ID of the agent this inbox belongs to
  - `createdAt` string, date-time, required: Timestamp when the inbox was created

## Other responses

- `402`: 402
- `403`: 403
- `404`: 404
- `409`: 409

---

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