v13

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-08-04237161688.6 KB

Email Addresses

Replace a user's 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.

put/users/{user_id}/email_address

Path parameters

user_idstring required

The ID of the user whose email address to replace

Request body

email_addressstring 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_changedboolean 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

Success

idstring

object'email_address' required

String representing the object's type. Objects of the same type share the same value.

email_addressstring required

reservedboolean required

matches_sso_connectionboolean

Indicates whether this email address domain matches an active enterprise connection.

created_atinteger required

Unix timestamp of creation

updated_atinteger required

Unix timestamp of creation