---
title: "Claim a vanity inbox name"
method: POST
path: "/managed-inbox/vanity"
tags: ["Domains"]
---

# Claim a vanity inbox name

`POST /managed-inbox/vanity`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/managed-inbox/vanity`
- Auth: HTTP bearer

Make the name the organization's current managed inbox. The previous inbox stops being current but keeps receiving mail. Needs the Power plan and domains:manage, which a credential confined to some mailboxes never holds. Sending records are published in the same request when they can be. outbound_ready false means they could not be yet: mail to the new name still arrives, but sending from it is refused until they are published.

## Headers

- `Idempotency-Key` string

## Request body

- ClaimVanityInboxNameRequest
  - `name` string, required

## Response `201`

Claim a vanity inbox name

- object
  - `success` true, required
  - `data` ClaimVanityInboxNameResult, required
    - `subdomain` string, required
    - `domain` string, required
    - `outbound_ready` boolean, required

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `402`: plan_required: renaming the inbox needs the Power plan.
- `403`: Authenticated caller lacks permission for the operation
- `409`: conflict: the name is already taken, or another change to the organization's inbox committed meanwhile (retry).
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

---

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