Send & Receive Masked Email Messages

Email Mask addresses automatically route email messages to and from the user's real email address they have chosen to associate with the mask via the verification process.

The handling of email messages being routed via an Email Mask is different depending on where the users real email address is hosted, those are:

• Internal Email Mask: Where the real address is another Sudo Platform owned Email Address hosted in your Sudo Platform deployment.

• External Email Masks: Where the real address is an externally hosted email account.

Internal Email Masks

An Internal Email Mask allows the user to freely send and receive messages via their Mask, without exposing their real email address to other participants in the email chain.

Inbound Message Receiving

When the Sudo Platform Email Service receives an email message to an Internal Email Mask it is processed in almost an identical manner as emails sent directly to an Email Address. It will be placed in the INBOX of the Email Address and can be distinguished from other messages by the presence of the emailMaskId property on the emailMessage object. These messages can be retrieved the same way as any other message as described in Receiving Email Messages

Outbound Message Sending

Users can send messages directly using their Internal Email Mask. To do this, invoke the sendMaskedEmailMessage method. This works in much the same way as usual, including with the ability to send end-to-end encrypted messages where possible. See Send & Receive Email Messages for more detail

TypeScript

// Collect the input headers, body, attachments and sender email mask id 
// however makes sense for your implementation.
const senderEmailMaskId: string = emailMask.id 
const emailMessageHeader: InternetMessageFormatHeader = {
    from: { emailAddress: "[e-mail]" }, // Must match emailMask.maskAddress
    to: [{ emailAddress: "[e-mail]" }],
    cc: [{ emailAddress: "[e-mail]" }],
    bcc: [{ emailAddress: "[e-mail]" }],
    replyTo: [{ emailAddress: "[e-mail]" }],
    subject: "Example subject line",
}
const emailAttachment: EmailAttachment = {
    filename: "fooAttachment.pdf",
    contentId: uuid.v4(),
    mimeType: "application/pdf",
    inlineAttachment: false,
    data: // ... Some pdf data
}
const inlineAttachment: EmailAttachment = {
    filename: "fooImage.png",
    contentId: uuid.v4(),
    mimeType: "image/png",
    inlineAttachment: true,
    data: // ... Some image data
}
try {
    const input: SendMaskedEmailMessageInput = {
        senderEmailMaskId: senderEmailMaskId,
        emailMessageHeaders: emailMessageHeader,
        body: "An example email body",
        attachments: [emailAttachment],
        inlineAttachments: [inlineAttachment],
    }
    const result = await emailClient.sendMaskedEmailMessage(input)
    // `result` contains the identifier and created timestamp associated with the sent email message. You can use this to access the data of the email message.
} catch {
    // Handle/notify user of error 
}

Swift

/// Collect the input headers, body, attachments and sender email mask id 
/// however makes sense for your implementation.
let senderEmailMaskId: String = emailMask.id
let emailMessageHeader = InternetMessageFormatHeader(
    from: EmailAddressDetail(emailAddress: "[e-mail]"), // Must match emailMask.maskAddress
    to: [EmailAddressDetail(emailAddress: "[e-mail]")],
    cc: [EmailAddressDetail(emailAddress: "[e-mail]")],
    bcc: [EmailAddressDetail(emailAddress: "[e-mail]")],
    replyTo: [EmailAddressDetail(emailAddress: "[e-mail]")],
    subject: "Example subject line"
)
let emailAttachment = EmailAttachment(
    filename: "fooAttachment.pdf",
    contentId: UUID().uuidString,
    mimetype: "application/pdf",
    inlineAttachment: false,
    data: // ... Some pdf data
)
let inlineAttachment = EmailAttachment(
    filename: "fooImage.png",
    contentId: UUID().uuidString,
    mimetype: "image/png",
    inlineAttachment: true,
    data: // ... Some image data
)
do {
    let input = SendMaskedEmailMessageInput(
        senderEmailMaskId: senderEmailMaskId,
        emailMessageHeaders: emailMessageHeader,
        body: "An example email body",
        attachments: [emailAttachment],
        inlineAttachments: [inlineAttachment]
    )
    let result = try await emailClient.sendMaskedEmailMessage(
        withInput: input
    )
    /// `result` contains the identifier and created timestamp associated with the sent email message. You can use this to access the data of the email message.
} catch {
    /// Handle/notify user of error
}

Kotlin

// Collect the input headers, body, attachments and sender email mask id 
// however makes sense for your implementation.
val senderEmailMaskId: String = emailMask.id
val emailMessageHeader = InternetMessageFormatHeader(
    from = EmailMessage.EmailAddress("[e-mail]"), // Must match emailMask.maskAddress
    to = listOf(EmailMessage.EmailAddress("[e-mail]")),
    cc = listOf(EmailMessage.EmailAddress("[e-mail]")),
    bcc = listOf(EmailMessage.EmailAddress("[e-mail]")),
    replyTo = listOf(EmailMessage.EmailAddress("[e-mail]")),
    subject = "Example subject line",
)
val emailAttachment = EmailAttachment(
    fileName = "fooAttachment.pdf",
    contentId = UUID.randomUUID().toString(),
    mimeType = "application/pdf",
    inlineAttachment = false,
    data = // ... Some pdf data
)
val inlineAttachment = EmailAttachment(
    fileName = "fooImage.png",
    contentId = UUID.randomUUID().toString(),
    mimeType = "image/png",
    inlineAttachment = true,
    data = // ... Some image data
)
launch {
    try {
        val input = SendMaskedEmailMessageInput(
            senderEmailMaskId = senderEmailMaskId,
            emailMessageHeaders = emailMessageHeader,
            body = "An example email body",
            attachments = listOf(emailAttachment),
            inlineAttachments = listOf(inlineAttachment),
        )
        val result = withContext(Dispatchers.IO) {
            emailClient.sendMaskedEmailMessage(input)
        }
        // [result] contains the identifier and created timestamp associated with the sent email message. You can use this to access the data of the email message.
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

External Email Masks

An External Email Mask handles messages significantly differently to Internal Email Masks. The Sudo Platform Email Service does not store a copy of the body or other headers of messages it receives for External Email Masks. Instead, it adjusts the headers then forwards the message to the user's real email address. There are no methods in the Sudo Email SDK associated with sending or receiving messages associated with an External Email Mask.

Inbound Message Receiving

The Sudo Platform Email Service must make some changes to the headers of an email before forwarding it to the user's real email address.

For the following example, assume the following:

• The domain set up for Email Masks in the Sudo Platform is mask.sudoplatform.com

• Email Mask

  • Mask address: [e-mail]

  • External email address: [e-mail]

• Sender's address: [e-mail]

When a message is received that has been sent to [e-mail] from [e-mail], the Sudo Platform Email Service makes the following changes to the message headers before forwarding the message to [e-mail]:

• The From header is changed to "[e-mail] via" <[e-mail]>

• The To header (or Cc if that was used) is changed to [e-mail]

• The Reply-To header is changed to [e-mail]

The service will then forward the message to [e-mail] and store the message identifier along with the emailMaskId and the sender's address securely in order to allow for future replies to be handled.

Outbound Message Sending

A user can reply to messages received via their External Email Mask from their preferred email client, by the standard email reply flow. The message will be sent to [e-mail] , processed by the Sudo Platform Email Service, and forwarded to the original sender.

Important: A user cannot initiate an email chain via an External Email Mask. They can only reply to messages they have already received. That is, there is no way for [e-mail] to send an email to [e-mail] except as a reply to an email from [e-mail].

Continuing with the above example, when a message is received that has been sent to [e-mail], from [e-mail], the Sudo Platform Email Service will read the In-Reply-To header of the message to get the id of the original message and attempt to retrieve the record associated with it. If it is available, it will look up the Email Mask associated with the emailMaskId and the original sender's email address. It will then make the following changes to the message headers:

• The From header is changed to [e-mail]

• The To header is changed to [e-mail]

The service will also make an effort to remove any other headers that may contain [e-mail] . The message is then forwarded to [e-mail] .