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

# Create an inbox

`POST /v1/inboxes`

## Request

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

Creates an address that receives mail. Omit `domain` for an inbox on the shared domain — ready immediately, no DNS. To use your own domain, it must be verified in this project and its MX record must already point at `inbound-smtp.<region>.amazonaws.com`; use a dedicated subdomain (e.g. `agents.yourcompany.com`), never the domain your team's mail lives on — a domain whose MX points elsewhere is refused with `domain_receives_elsewhere`.

Pass `clientId` to make creation idempotent: a repeat returns the existing inbox with 200. Addresses are never recycled — a deleted inbox's address can't be created again by anyone.

## Request body

- object
  - `username` string: Local part. Random (`inbox-…`) if omitted.
  - `domain` string: A verified domain of yours. Omit for the shared domain.
  - `displayName` string, nullable
  - `clientId` string
  - `metadata` object
  - `securityMode` 'off' | 'tag' | 'hold'

## Response `200`

An inbox with this `clientId` already existed.

- Inbox
  - `inboxId` string, required
  - `address` string, email, required
  - `domain` string, required
  - `kind` 'shared' | 'custom', required: `shared`: on the platform's shared inbox domain, no DNS needed. `custom`: on a domain of your own.
  - `displayName` string, nullable: Used as the From name on mail sent from this inbox.
  - `status` 'active' | 'paused' | 'deleted', required
  - `securityMode` 'off' | 'tag' | 'hold': Scan received mail for attempts to manipulate an AI agent. `tag`: deliver now, label `security-review` if flagged. `hold`: withhold from the agent (no `email.received`, hidden from reads) until the scan clears it or a project key releases it.
  - `clientId` string, nullable: Your idempotency key from creation, if you passed one.
  - `metadata` object, nullable
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `201`: Created.
- `401`: Missing or invalid API key.
- `403`: Inboxes not enabled for this project, the plan's inbox limit is reached, or the domain is not verified.
- `409`: Address taken, or the domain's MX record is missing or points elsewhere.
- `422`: Request validation failed (code `validation_error`, 422).

---

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