Clerk API (unofficial showcase)
PATCH/email_addresses/{email_address_id}

Update an email address

Updates an existing email address's verification or primary status, or its notification behavior. Supply any of verified, primary, or notify_primary_email_address_changed to change that setting. The notification option applies when the update makes this address the user's new primary address.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
email_address_idstringrequired
The unique identifier of the email address to update.

Email address settings to update. Supply the fields whose values you want to change.

verifiedbooleanoptional
The email address will be marked as verified.
primarybooleanoptional
Set this email address as the primary email address for the user.
notify_primary_email_address_changedbooleanoptional
If set to `true` and this update makes the email address the user's new primary, the previous primary email address is notified of the change. By default, no notification is sent.
Default:false

6 status codes
200Returns the updated email address object, including its address, verification details, linked resources, reserved status, and timestamps.
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
400Returned when the request is not successful.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Returned when authentication is invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Returned when authorization is invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Returned when the email address resource is not found.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
409Returned when the request conflicts with the current state.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

An invalid request returns a 400, invalid authentication returns a 401, and invalid authorization returns a 403. The email_address_id path parameter must identify an existing email address; a 404 indicates the resource was not found, and a 409 indicates a conflict with the current state.