---
title: "Reserve a chosen inbox name before account registration or sign-in"
method: POST
path: "/onboarding/start"
tags: ["public"]
---

# Reserve a chosen inbox name before account registration or sign-in

`POST /onboarding/start`

## Request

- Base URL: `https://api.mailly.site` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mailly.site/onboarding/start`
- Auth: none required

Shared by agents and the web page. Reserve name@mailly.site for 30 minutes. No account, receiving mailbox or mail access is created. Return 409 name_taken if registered or reserved. Give the verification URL to the human and keep the setup token private.

## Request body

- object
  - `name` string, required

## Response `200`

Give verification_url to the human; keep setup_token secret

- object
  - `success` boolean, required
  - `request_id` string, required
  - `address` string, required
  - `verification_url` string, required
  - `status_url` string, required
  - `setup_token` string, required
  - `expires_in` number, required
  - `interval` number, required

## Other responses

- `202`: Waiting for human approval
- `400`: Invalid request
- `401`: Authentication required
- `403`: Not allowed
- `409`: Address unavailable or request already handled
- `410`: Request expired
- `429`: Too many requests
- `503`: Temporarily unavailable

---

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