Display an email identifier
An account settings screen needs to show a user's current email address.
Clerk · Class
EmailAddress
EmailAddress is Clerk's model for a user's email identifier, including its value, identity metadata, linked identifications, and verification state. Use its methods to start verification, remove the address, or obtain its string value.
How it works
EmailAddress represents one email identifier belonging to the current user. It exposes the address value, identity metadata, and verification state, and provides methods for creating, deleting, stringifying, and beginning verification.
Syntax
class EmailAddressReturns
An EmailAddress object exposes the email address, its identifier and metadata, verification state, and linked identifications; toString() returns the address value.
Key points
- Use EmailAddress as the SDK model for a user's email identifier.
- An email address can serve as one of the identifiers Clerk uses to identify a user.
- The object carries the state needed while the address moves through verification.
- The id property uniquely identifies this email-address resource.
- Read emailAddress to obtain the actual address string.
- matchesSsoConnection indicates whether the address corresponds to an SSO connection.
- destroy() removes the email address from the current user.
- toString() provides the address value for string contexts or display.
Common mistakes
- Do not treat an email address as trusted until its verification status confirms ownership.
- Track verification through the object's verification property rather than assuming that an address is verified after creation.
Example: Check a verified email address
const email = user.primaryEmailAddress;
if (email?.verification?.status === "verified") {
console.log(email.toString());
}Reads the current user's primary email and uses its verification status before displaying the address.
When to use it
Begin email verification
An application must start ownership confirmation for a newly added address.
Delete an email address
A profile-management flow removes an obsolete address from the current user.
Gate access on verification
A security-sensitive action requires confirmed email ownership.
Interview questions
QWhat does the EmailAddress object represent?
EmailAddress is a model for an email identifier associated with a user. Its properties include the address value, a unique ID, SSO-match information, verification state, and linked identifications.
Follow-up: How would you determine whether it is safe to use the address? Check the verification property's status and require the verified state before treating ownership as confirmed.
QHow does email verification begin?
Call prepareVerification() to start verification. Clerk then sends either an OTP or a verification link according to the selected strategy and dashboard configuration.
Follow-up: What should be inspected after preparation? Read the verification property to track the resulting verification state.
QWhat are the primary instance methods?
toString() returns the email value, which is also available through the emailAddress property. destroy() deletes the email address from the current user.
Follow-up: Which operation should be used when only formatting the object for display? Use toString(), not destroy(), because destroy() removes the address.
Related
UserVerificationResourceIdentificationLinkResourceprepareVerification()attemptVerification()