---
title: "POST /v1/handles"
method: POST
path: "/v1/handles"
---

# POST /v1/handles

`POST /v1/handles`

## Request

- The document declares no server URL.
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-better-auth.session_token`

Claim an address on one of this organisation's domains.

## Request body

- HandleCreate
  - `domainId` string, required: One of this organisation's domains. The address's `@`-side comes from it, never from a string.
  - `localPart` string, required: The part before the `@`, lowercased: letters, digits, dots, underscores and hyphens, up to 64 — a dot never first, last or doubled (`first.last` is fine). `+` is never part of a name: it is plus-addressing, so `sales+news@` reaches `sales@`. Or `*`, the domain's **catch-all**, which receives every address on the domain that no other handle claims (role addresses such as `postmaster` included) once it is routed. There is no catch-all unless one is claimed: until then an unclaimed address bounces. `unsubscribe` and `cf-bounce` are the platform's own and refused.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- Handle
  - `id` string, required
  - `domainId` string, required: The domain this local part sits on.
  - `localPart` string, required
  - `address` string, required: The composed address, `localPart@domain` — what the world writes to. `*@domain` for the catch-all.
  - `createdAt` string, date-time, required

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/foundermail/apis/org.md) - [All operations](https://skmtc.dev/foundermail/apis/org/llms.txt) - [OpenAPI document](https://skmtc.dev/foundermail/apis/org/revisions/8bbb36e378ab?raw)