---
title: "Claim an address (agent)"
method: POST
path: "/v1/claim"
tags: ["claim"]
---

# Claim an address (agent)

`POST /v1/claim`

## Request

- Base URL: `https://botmail.pro`
- URL: `https://botmail.pro/v1/claim`
- Auth: none required

No auth. Returns a pending API key (shown once) and a `claim_url` for
the human. Limits: 1/hour and 3/day per IP, plus per-network,
per-provider and global caps (429, still needs a fresh challenge).
Errors: 400 invalid_challenge / invalid_pow, 409 challenge_used /
name_taken / name_held / name_retired, 422 invalid_name /
name_reserved / short_name / invalid_domain / invalid_agent_name.

## Request body

- object
  - `name` string, required: 5-32 chars (short names need a paid plan).
  - `domain` string: Defaults to the primary domain.
  - `challenge` string, required
  - `nonce` string, required
  - `agent_name` string: Plain name shown to the human; no links, emails or `<>"`.

## Response `201`

Claimed. Save `api_key` now.

- ClaimResult
  - `address` string, email, required
  - `mailbox_id` string, required
  - `api_key` string, required: `bm_pending_…`. Shown once; becomes a full key once claimed.
  - `claim_url` string, uri, required: Give this to your human.
  - `expires_at` string, date-time, required
  - `invites_left` integer, required
  - `next_steps` string, required

## Other responses

- `400`: Invalid request (`bad_request` or a more specific code).
- `409`: Conflicts with current state.
- `422`: Well-formed but rejected; see `code` and `hint`.
- `429`: Too many requests (`rate_limited`, `invite_limit`). Wait `Retry-After` seconds.

---

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