Docs

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 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 attemptVerification() method, passing the one-time code as a parameter.

Properties

  • Name
    id
    Type
    string
    Description

    A unique identifier for this email address.

  • Name
    emailAddress
    Type
    string
    Description

    The value of this email address.

  • Name
    verification
    Type
    Verification
    Description

    An object holding information on the verification of this 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 this email address.

Methods

create()

Creates a new email address for the current user.

function create(): Promise<EmailAddress>;

destroy()

Deletes this email address.

function destroy(): Promise<void>;

toString()

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

function toString(): string;

prepareVerification()

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

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

PrepareEmailAddressVerificationParams

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

    The verification strategy.
    Possible strategy values 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

    The email link target URL. Users will be redirected here once they click the email link from their email. This param only applies if strategy is email_link.

attemptVerification()

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.

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.

The first function is async and starts the email link flow, preparing a email link verification. It sends the email link email and starts polling for verification results. The signature is startEmailLinkFlow({ 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 cancelEmailLinkFlow() => void.

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

Returns

createEmailLinkFlow returns an object with two functions:

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

    Function to start the email link flow. It prepares a email link verification and polls for the verification result.

  • Name
    cancelEmailLinkFlow
    Type
    () => void
    Description

    Function to cleanup the email link flow. Stops waiting for verification results.

  • Name
    redirectUrl
    Type
    string
    Description

    The email link target URL. Users will be redirected here once they click the email link from their email.

Feedback

What did you think of this content?
Edit this page on GitHub