---
title: "Set a user's email address."
method: PUT
path: "/api/users/{username}/email"
tags: ["Users"]
---

# Set a user's email address.

`PUT /api/users/{username}/email`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/users/{username}/email`
- Auth: HTTP bearer

Sets or removes a user's email address. An address must have one @, something on each side, a dot in the domain, and no whitespace, and be at most 254 characters; a null or empty email removes it. The email address is not how a user is addressed or signs in, so changing it changes nothing else. Requires an administrator as well as the scope. Recorded as a user_email_changed audit event naming the calling administrator as the principal and the calling API key in the details; the address itself is not recorded. Requires the `users:write` scope.

## Path parameters

- `username` string, required

## Headers

- `Authorization` string, required

## Request body

- SetUserEmailRequest
  - `email` string: The new email address. null or empty removes the user's email address.

## Response `200`

The email address was set or removed.

- UserResponse
  - `email` string
  - `active` boolean
  - `created` string, date-time
  - `deactivatedAt` string, date-time
  - `id` string: The user's id, which audit events and other records refer to the user by.
  - `mfaEnabled` boolean: Whether the user is enrolled in TOTP multi-factor authentication. The secret is never returned.
  - `mfaLocked` boolean: Whether the user's MFA is locked after repeated bad codes, until an administrator unlocks it.
  - `passwordChangeRequired` boolean: Whether the user must change their password at next sign-in, because an administrator set it.
  - `passwordSet` boolean: Whether the user has a password. A user without one can only use API keys.
  - `role` string
  - `username` string

## Other responses

- `400`: The email address is not valid or too long.
- `401`: The Authorization header is absent or the API key is not recognized.
- `403`: The key does not hold users:write, or the caller is not an administrator.
- `404`: There is no user with that username.
- `406`: No representation matches Accept.
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-10** `c4f85daa9208`: 14 info
  - added the optional property `field` to the response with the `400` status
  - added the optional property `field` to the response with the `401` status
  - added the optional property `field` to the response with the `403` status
  - added the optional property `field` to the response with the `413` status
  - …10 more
- **2026-10-10** `51b359ecbb06`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/philterd/apis/philter-api/changes/api/users/:username/email/put.md)

---

[API](https://skmtc.dev/philterd/apis/philter-api.md) - [All operations](https://skmtc.dev/philterd/apis/philter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/philterd/apis/philter-api/revisions/aa3d7ad1aab4?raw)