---
title: "Mint a new alias."
method: POST
path: "/v1/addresses"
tags: ["Addresses"]
---

# Mint a new alias.

`POST /v1/addresses`

## Request

- Base URL: `https://api.inboxy.net`
- URL: `https://api.inboxy.net/v1/addresses`
- Auth: HTTP bearer

Requires `manage` scope. `type` picks the shape: `standard` (default, `adjective-noun-NN`), `agent` (`agent-xxxxxxxx`, flagged `kind: agent`) or `domain` (`yourdomain.com-xxxxxxxx`, flagged `kind: agent`, needs `domain_id` or `domain` naming one of your verified domains — `invalid_domain`, 400 otherwise). Standard aliases are gated by the open-address count cap (`cap_reached`, 403, body carries `used`/`limit`) and the Early-Adopter rotation cooldown (`rotation_cooldown`, 429, body carries `retry_after_sec`/`next_allowed_at`). `agent` and `domain` aliases share a separate agent allowance (`cap_reached`, 403, `pool: "agent"`) and skip the cooldown.

## Request body

- AddressCreate
  - `label` string: Optional user-facing label.
  - `scheme` 'adjective-noun' | 'opaque': Generation scheme for `standard` aliases. `adjective-noun` → e.g. brisk-otter-42; `opaque` → random.
  - `type` 'standard' | 'agent' | 'domain': `agent` → agent-xxxxxxxx; `domain` → yourdomain.com-xxxxxxxx (requires `domain_id`). Both are flagged `kind: agent`.
  - `domain_id` string, uuid: A verified domain's id (from `GET /v1/domains`). Required (or `domain`) when `type` is `domain`.
  - `domain` string: Alternative to `domain_id`: the verified domain's hostname, e.g. `nike.com`.

## Response `201`

Created.

- Address
  - `id` string, uuid, required
  - `local_part` string, required
  - `full_address` string, email, required
  - `label` string, nullable
  - `status` 'active' | 'retired', required
  - `kind` 'standard' | 'agent': `agent` aliases draw from the separate agent allowance.
  - `created_at` integer, required
  - `retired_at` integer, nullable
  - `total` integer: Total messages ever received at this alias (list-view only).
  - `unread` integer: Unread messages currently on this alias (list-view only).

## Other responses

- `400`: Malformed request.
- `403`: Token lacks the required scope.

---

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