Clerk API (unofficial showcase)
PUT/users/{user_id}/email_address

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.

1 parameter · 3 body fields
user_idstringrequired
The ID of the user whose email address to replace
email_addressstringrequired
The new email address. Must adhere to the RFC 5322 specification for email address format.
identification_statusstringoptional
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.
Allowed:verifiedreservedunverifiedDefault:verified
notify_primary_email_address_changedbooleanoptional
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.
Default:false

6 status codes
200Success
idstringoptional
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:email_address
email_addressstringrequired
reservedbooleanrequired
verificationobjectrequired
linked_toarray<object>required
matches_sso_connectionbooleanoptional
Indicates whether this email address domain matches an active enterprise connection.
created_atintegerrequired
Unix timestamp of creation
updated_atintegerrequired
Unix timestamp of creation
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.