Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

EmailAddress

The EmailAddress object is a model around an email address. Email addresses are used to provide identification for users.

Email addresses must be verified to ensure that they can be assigned to their rightful owners. The EmailAddress object holds all necessary state around the verification process.

The verification process always starts with the EmailAddress.prepareVerification() method, which will send a one-time verification code via an email message. The second and final step involves an attempt to complete the verification by calling the EmailAddress.attemptVerification() method, passing the one-time code as a parameter.

Finally, email addresses can be linked to other identifications.

Properties

NameTypeDescription
idstringA unique identifier for this email address.
emailAddressstringThe value of this email address.
verificationVerificationAn object holding information on the verification of this email address.
linkedToArray<{id: string, type: string}>An array of objects containing information about any identifications that might be linked to this email address.

Methods

create()

function create(): Promise<EmailAddress>;

Creates a new email address for the current user.

destroy()

function destroy(): Promise<void>;

Deletes this email address.

toString()

function toString(): string;

Returns the value for this email address. Can also be accessed via the EmailAddress.emailAddress attribute.

function createMagicLinkFlow(): { startMagicLinkFlow: (params: StartMagicLinkFlowParams) => Promise<EmailAddress>; cancelMagicLinkFlow: () => void; };

Sets up an email verification with magic link flow. Calling createMagicLinkFlow() will return two functions.

The first function is async and starts the magic link flow, preparing a magic link verification. It sends the magic link email and starts polling for verification results. The signature is startMagicLinkFlow({ redirectUrl: string }) => Promise<EmailAddress>.

The second function can be used to stop polling at any time, allowing for full control of the flow and cleanup. The signature is cancelMagicLinkFlow() => void.

Returns

createMagicLinkFlow returns an object with two functions:

NameTypeDescription
startMagicLinkFlow(params: StartMagicLinkFlowParams) => Promise<EmailAddress>Function to start the magic link flow. It prepares a magic link verification and polls for the verification result.
cancelMagicLinkFlow() => voidFunction to cleanup the magic link flow. Stops waiting for verification results.
NameTypeDescription
redirectUrlstringThe magic link target URL. Users will be redirected here once they click the magic link from their email.

Additional methods

In addition to the methods listed above, the EmailAddress class also has the following methods:

Validation

Last updated on October 10, 2023

What did you think of this content?

Clerk © 2024