---
title: "Choose your username"
description: "Sets the username of the person for good, and with it their free address."
url: "https://openemail.uk/docs/api/account/username-set"
area: "API"
category: "Your account"
---

# Choose your username

Sets the username of the person for good, and with it their free address.

`PUT /account/username`

## PUT /account/username

Sets the username of the person for good, and with it their free address.

## Example

Needs `account:write`. `username` has to be 3 to 30 lowercase letters, numbers and single dots once it is lowercased and its spaces become dots. Answers with the username, now chosen.

**curl**

```
curl -X PUT "$OE/account/username" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "username": "ada.lovelace" }'
```

**Response**

```
{
  "object": "username",
  "username": "ada.lovelace",
  "chosen": true,
  "address": "ada.lovelace@openemail.uk"
}
```

> Once chosen it never changes, so a second choice is a 409 `username_locked`. Check one first with `GET /account/username/availability`.

> A username another account has is a 409 `username_taken`. One that is too short, too long, reserved or not written as above is a 422 `invalid_parameter` on `username`, and the message says which.

## Reference

- [`PUT /account/username`](https://openemail.uk/docs/api/reference/your-account#put-account-username): full reference