---
title: "Accept a claim (human)"
method: POST
path: "/v1/claim/accept"
tags: ["claim"]
---

# Accept a claim (human)

`POST /v1/claim/accept`

## Request

- Base URL: `https://botmail.pro`
- URL: `https://botmail.pro/v1/claim/accept`
- Auth: API key in cookie `bm_session`

Signed-in human (session cookie) only. Moves the mailbox, its mail and
the agent's key into the human's account; the key gains full access.
Idempotent for the same account. Errors: 402 plan_limit,
403 account_inactive, 404 claim_not_found, 409 already_claimed.
Rate limit: 20/hour per account.

## Request body

- object
  - `token` string, required

## Response `200`

Claimed.

- object
  - `status` 'claimed', required
  - `mailbox` Mailbox, required
    - `id` string, required
    - `name` string, required
    - `display_name` string, required
    - `status` 'pending' | 'active' | 'suspended', required
    - `address` string, email, required: Primary address.
    - `addresses` string[], required: Every address, primary first (paid plans get the name on all domains).
    - `created_at` string, date-time, required

## Other responses

- `400`: Invalid request (`bad_request` or a more specific code).
- `401`: Missing or invalid credentials (`unauthorized`, `invalid_token`).
- `402`: Plan limit or payment needed (`plan_limit`, `payment_required`). Upgrade, then retry.
- `403`: The credential can't do this (`forbidden`, `csrf`, `account_inactive`, …). Missing scopes are listed in `details.required_scope`; pending keys get a hint to wait for the claim.
- `404`: Not found or not accessible with this credential.
- `409`: Conflicts with current state.
- `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)