Skip to main content
Docs

EmailAddress

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

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

  1. Initiate the verification process by collecting the user's email address.
  2. Prepare the verification process by calling the prepareVerification() method, which will send a one-time verification code via an email link or code, depending on what parameters are passed to the method and the settings in the Clerk Dashboard.
  3. Attempt to complete the verification by calling the attemptVerification() method, passing the one-time code as a parameter.

For implementation examples for adding and verifying email addresses, see the email link custom flow and email code custom flow guides.

Properties

  • Name
    id
    Type
    string
    Description

    The unique identifier for the email address.

  • Name
    emailAddress
    Type
    string
    Description

    The value of the email address.

  • Name
    verification
    Type
    Verification
    Description

    An object holding information on the verification of the email address.

  • Name
    linkedTo
    Type
    Array<{id: string, type: string}>
    Description

    An array of objects containing information about any identifications that might be linked to the email address.

Methods

create()

Creates a new email address for the current user.

function create(): Promise<EmailAddress>

destroy()

Deletes the email address.

function destroy(): Promise<void>

toString()

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

function toString(): string

prepareVerification()

Initiates the email address verification process. Based on the specified strategy, sends either a one-time verification code or a verification link to the email address. The verification status can be tracked through the verification property of the EmailAddress object.

function prepareVerification(params: PrepareEmailAddressVerificationParams): Promise<EmailAddress>

PrepareEmailAddressVerificationParams

  • Name
    strategy
    Type
    'email_link' | 'email_code'
    Description

    The verification strategy. Supported strategies are:

    • email_link: User will receive an email link via email.
    • email_code: User will receive a one-time authentication code via email.
  • Name
    redirectUrl
    Type
    string | undefined
    Description

    Required if strategy is set to email_link. The full URL that the user will be redirected to when they visit the email link. See the custom flow for implementation details.

attemptVerification()

Attempts to verify an email address using a one-time code. The code must have been previously sent to the email address via the EmailAddress.prepareVerification() method with strategy: 'email_code'. Returns the updated EmailAddress object if verification is successful.

function attemptVerification(params: AttemptEmailAddressVerificationParams): Promise<EmailAddress>

AttemptEmailAddressVerificationParams

  • Name
    code
    Type
    string
    Description

    The one-time code that was sent to the user's email address when EmailAddress.prepareVerification() was called with strategy set to email_code.

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

function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: StartEmailLinkFlowParams) => Promise<EmailAddress>
  cancelEmailLinkFlow: () => void
}

createEmailLinkFlow returns an object with two functions:

  • Name
    startEmailLinkFlow
    Type
    (params: StartEmailLinkFlowParams) => Promise<EmailAddress>
    Description

    Function to start the email link flow. It sends the email with the email link and polls for the verification result.

  • Name
    cancelEmailLinkFlow
    Type
    () => void
    Description

    Function to stop polling for the verification result, allowing for full control of the flow and cleanup.

  • Name
    redirectUrl
    Type
    string
    Description

    The full URL that the user will be redirected to when they visit the email link.

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on