---
title: "Replace a user's email address"
method: PUT
path: "/users/{user_id}/email_address"
tags: ["Email Addresses"]
---

# Replace a user's email address

`PUT /users/{user_id}/email_address`

Replaces all of the user's email addresses with a single primary email address.
By default the new email address is created verified, with the admin verification strategy.
When `identification_status` is `reserved` it is created reserved instead: unverified but usable
for sign-in and locked so no other user can claim it. When it is `unverified` the address is
neither usable for sign-in nor locked. Any existing email addresses are deleted.
If an existing email address is linked to a connected account, the request is rejected; remove
the connected account first.

**Warning:** `identification_status: unverified` can lock the user out of their account. An
unverified email address cannot be used to sign in, so if the user has no other verified or
reserved identifier, deleting their existing email addresses leaves them unable to
authenticate — and unable to verify the new address, since that requires signing in. Recovery
then requires another admin API call.

## Path parameters

- `user_id` string, required

## Request body

- object
  - `email_address` string, required — The new email address. Must adhere to the RFC 5322 specification for email address format.
  - `identification_status` 'verified' | 'reserved' | 'unverified' — Controls the status of the replacement email address. Defaults to `verified`. Set to `reserved` to create it reserved (unverified but usable for sign-in and locked so no other user can claim it), or to `unverified` to create it neither usable for sign-in nor locked. **Warning:** `unverified` can lock the user out of their account. An unverified email address cannot be used to sign in, so if the user has no other verified or reserved identifier, they will be unable to authenticate and unable to verify this address. Prefer `reserved` unless you specifically need the address left unclaimed — for example so that another user can also hold it until one of them verifies it.
  - `notify_primary_email_address_changed` boolean, nullable — If set to `true`, the user's previous primary email address is notified that the primary email address has changed. No notification is sent when the replacement is the user's current primary email address. By default, no notification is sent.

## Response `200`

Success

- EmailAddress
  - `id` string
  - `object` 'email_address', required — String representing the object's type. Objects of the same type share the same value.
  - `email_address` string, required
  - `reserved` boolean, required
  - `verification` union, required
    - object
      - `object` 'verification_otp'
      - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
      - `strategy` 'phone_code' | 'email_code' | 'reset_password_email_code', required
      - `attempts` integer, nullable, required
      - `expire_at` integer, nullable, required
      - `channel` string, nullable — The delivery channel of the code (phone codes only).
      - `verified_at_client` string, nullable
    - object
      - `object` 'verification_admin'
      - `status` 'verified', required
      - `strategy` 'admin', required
      - `attempts` integer, nullable, required
      - `expire_at` integer, nullable, required
      - `verified_at_client` string, nullable
    - object
      - `object` 'verification_from_oauth'
      - `status` 'unverified' | 'verified', required
      - `strategy` string, required
      - `error` object, nullable
        - `message` string, required
        - `long_message` string, required
        - `code` string, required
        - `meta` object
      - `expire_at` integer, nullable, required
      - `attempts` integer, nullable, required
      - `verified_at_client` string, nullable
    - object
      - `object` 'verification_ticket'
      - `status` 'unverified' | 'verified' | 'expired', required
      - `strategy` 'ticket', required
      - `attempts` integer, nullable, required
      - `expire_at` integer, nullable, required
      - `verified_at_client` string, nullable
    - object
      - `object` 'verification_saml'
      - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
      - `strategy` 'saml', required
      - `external_verification_redirect_url` string, nullable
      - `error` object, nullable
        - `message` string, required
        - `long_message` string, required
        - `code` string, required
        - `meta` object
      - `expire_at` integer, nullable
      - `attempts` integer, nullable, required
      - `verified_at_client` string, nullable
    - object
      - `object` 'verification_email_link'
      - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
      - `strategy` 'email_link', required
      - `attempts` integer, nullable, required
      - `expire_at` integer, nullable, required
      - `verified_at_client` string, nullable
    - object
      - `object` 'verification_scim'
      - `status` 'verified', required
      - `strategy` 'scim', required
      - `attempts` integer, nullable, required
      - `expire_at` integer, nullable, required
  - `linked_to` IdentificationLink[], required
    - `type` string, required
    - `id` string, required
  - `matches_sso_connection` boolean — Indicates whether this email address domain matches an active enterprise connection.
  - `created_at` integer, required — Unix timestamp of creation
  - `updated_at` integer, required — Unix timestamp of creation

## Other responses

- `400` — Request was not successful
- `401` — Authentication invalid
- `403` — Authorization invalid
- `404` — Resource not found
- `422` — Invalid request parameters

---

[API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/revisions/75df3a43fcb2/schema)