Clerk API (unofficial showcase)
POST/email_addresses

Create an email address

Creates a new email address for a user. Supply user_id and an RFC 5322-formatted email_address; optionally set verified or primary when creating it. If omitted, primary defaults to false unless this is the user's first email address.

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

5 body fields

Email address details to associate with a user. user_id and email_address are required.

user_idstringrequired
The ID representing the user
email_addressstringrequired
The new email address. Must adhere to the RFC 5322 specification for email address format.
verifiedbooleanoptional
When created, the email address will be marked as verified.
primarybooleanoptional
Create this email address as the primary email address for the user. Default: false, unless it is the first email address.
notify_primary_email_address_changedbooleanoptional
If set to `true` and the email address is created as the user's new primary, the previous primary email address is notified of the change. By default, no notification is sent.
Default:false

7 status codes
200Returns the created email address, 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 a referenced 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
422Returned when request parameters are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

user_id and email_address are required, and email_address must follow RFC 5322; an invalid or incomplete request returns a 400. Invalid authentication returns a 401, invalid authorization returns a 403, a missing resource returns a 404, and a conflicting request returns a 409. Invalid request parameters return a 422.