EmailAddress

The EmailAddress object describes a User's email address.

Overview

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

Email addresses must be verified, so that we can make sure 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.

Attributes

Name	Type	Description
id	string	A unique identifier for this email address.
emailAddress	string	The value of this email address, the actual email box address.
verification	VerificationResource	An object holding information on the verification of this email address.
linkedTo	IdentificationLinkResource	An object containing information about any identifications that might be linked to this email address

Methods

create()

create() => Promise<EmailAddressResource>

Creates a new email address for the current user.

Parameters

This method accepts no parameters.

Returns

Type	Description
Promise<void>	This method returns a Promise which doesn't resolve to any value.

prepareVerification()

prepareVerification(params: PrepareEmailAddressVerificationParams) => Promise<EmailAddressResource>

Kick off the verification process for this email address. An email message with a one-time code or a magic-link will be sent to the email address box.

Parameters
This method accepts no parameters.

Returns

Type	Description
Promise<EmailAddressResource>	This method returns a `Promise` which resolves with a `EmailAddress` object.

attemptVerification(code)

attemptVerification(params: AttemptEmailAddressVerificationParams) => Promise<EmailAddressResource>

Attempts to verify this email address, passing the one-time code that was sent as an email message. The code will be sent when calling the EmailAddress.prepareVerification() method.

Parameters

Name	Description
params	An object of type `AttemptEmailAddressVerificationParams`

Returns

Type	Description
Promise<EmailAddressResource>	This method returns a `Promise` which resolves with a `EmailAddress` object.

createMagicLinkFlow()

createMagicLinkFlow() => CreateMagicLinkFlowParams<StartMagicLinkFlowParams, EmailAddressResource>

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<EmailAddressResource>.

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

Type	Description
CreateMagicLinkFlowReturn<StartMagicLinkFlowParams, EmailAddressResource>	This method returns two functions. One to start the magic link flow and the other to cancel waiting for the results.

destroy()

destroy() => Promise<void>

Delete this email address.

Parameters

This method accepts no parameters.

Returns

Type	Description
Promise<void>	This method returns a Promise which doesn't resolve to any value.

toString()

toString() => string | null

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

Parameters

This method accepts no parameters.

Returns

Type	Description
string \| null	This method returns the email address attribute.

Interfaces

IdentificationLinkResource

Name	Type	Description
id	string	A unique identifier for the identification.
type	string	The identification type.

StartMagicLinkFlowParams

Name	Type	Description
redirectUrl	string	The magic link target URL. Users will be redirected here once they click the magic link from their email.

VerificationResource

Name	Type	Description
status	string \| null	The verification status. Possible values are: unverified: The verification process has not been completed. verified: The verification process has completed successfully. transferable: The verification can be transferred as part of an external account verification process. failed: The verification process has been completed, but failed. expired: The verification is invalid because it wasn't completed in the allowed time.
strategy	string \| null	The verification strategy. Possible strategy values are: email_code: User will receive a one-time authentication code via email. At least one email address should be on file for the user. The email_address_id parameter can also be specified to select one of the user's known email addresses. phone_code: User will receive a one-time authentication code in their phone, via SMS. At least one phone number should be on file for the user. The phone_number_id parameter can also be specified to select which of the user's known phone numbers the SMS will go to. password: The user needs to provide their password in order to be authenticated. oauth_google: The user will be authenticated with their Google account (Google SSO). oauth_facebook: The user will be authenticated with their Facebook account (Facebook SSO). oauth_hubspot: The user will be authenticated with their Hubspot account (Hubspot SSO). oauth_github: The user will be authenticated with their Github account (Github SSO). oauth_tiktok: The user will be authenticated with their TikTok account (TikTok SSO).
attempts	number \| null	The number of attempts to complete the verification so far. Usually, a verification allows for maximum 3 attempts to be completed.
expireAt	Date \| null	The timestamp when the verification will expire and cease to be valid.
error	ClerkAPIError \| null	Any error that occurred during the verification process from the Clerk API.
externalVerificationRedirectURL	URL \| null	If this is a verification that is based on an external account (usually oauth_*), this is the URL that the user will be redirected to after the verification is completed.

Types

PrepareEmailAddressVerificationParams

Name	Type	Description
strategy	string	The verification strategy. Possible strategy values are: email_code: User will receive a one-time authentication code via email. email_link: User will receive an email magic link via email.
redirectUrl	string \| undefined	The magic link target URL. Users will be redirected here once they click the magic link from their email. This param only applies if `strategy` is `email_link`

AttemptEmailAddressVerificationParams

Name	Type	Description
code	string	The one-time code that was sent to the user's email address when prepareVerification was called with `strategy` set to `email_code`

CreateMagicLinkFlowReturn<StartMagicLinkParams, EmailAddressResource>

{ startMagicLinkFlow: (params: StartMagicLinkFlowParams) => Promise<EmailAddressResource>, cancelMagicLinkFlow: () => void }

Name	Description
startMagicLinkFlow	Function that starts the magic link flow. It prepares a magic link verification and polls for the verification result. Accepts StartMagicLinkFlowParams. Returns a Promise which resolves to an EmailAddressResource.
cancelMagicLinkFlow	Function to cleanup the magic link flow. Stops waiting for verification results.