Verifying External Email Addresses

Ensuring that the user owns an external email address is a critical step in setting up an Email Mask to forward to that address.

If you provide the option to provision Email Masks that are associated with an external (i.e. Non-Sudo Platform Email Service) email address, the Mask will initially have its state set to PENDING. While in this state, the Mask will not be able to receive (or reply to) messages. In order to change its state to ENABLED , you must verify that the user owns the email address. To do this, you must call the verifyExternalEmailAddress method. This will trigger a One-Time Passcode (OTP) verification flow in which an email will be sent to the email address with a six-digit code that must then be passed into another call to verifyExternalEmailAddress for verification.

Note that this process is not needed for Email Masks associated with a Sudo Platform email address.

Sending the One-Time Passcode

To initiate the OTP flow, first call verifyExternalEmailAddress with the id of the Email Mask being enabled and the email address to verify.

TypeScript

const emailMaskId: string = emailMask.id // Get the Email Mask from the `provisionEmailMask` method
const emailAddress: string // The email address must match the one passed in as the `realAddress` property of `provisionEmailMask`
try {
    await emailClient.verifyExternalEmailAddress({
        emailMaskId: emailMaskId,
        emailAddress: emailAddress,
    })
    // At this point, the method should return `undefined`
} catch (e) {
    // Handle/notify user of errors
}

Swift

Kotlin

After this call, the user should receive an email from the Sudo Platform Email Service with the OTP that will need to be passed into the next call.

In order to use this functionality, you must define a domain for the email to come from, as well as provide an HTML template for the email body. Your solutions engineer can assist you in setting this up.

Verifying the One-Time Passcode

Once the user has received the OTP from their email address, it must be passed in to another call to verifyExternalEmailAddress to be verified by the service. If that is successful, the Email Mask will have its state updated to ENABLED and it will be ready to use.

TypeScript

const emailMaskId: string = emailMask.id // Get the Email Mask from the `provisionEmailMask` method
const emailAddress: string // The email address must match the one passed in as the `realAddress` property of `provisionEmailMask`
const verificationCode: string // The code that the user has retrieved from the email sent to their real email address
try {
    const result = await emailClient.verifyExternalEmailAddress({
        emailMaskId: emailMaskId,
        emailAddress: emailAddress,
        verificationCode: verificationCode
    })
    // `result.isVerified` will be true if verification was successful, and the Email Mask will have its state set to ENABLED
    // If it was not, then `result.reason` will contain a string with the reason it failed
} catch (e) {
    // Handle/notify user of errors
}

Swift

Kotlin