Email Masks automatically route messages sent to the to their associated real email address, and can (for Internal real email addresses) send messages without exposing the users real email address.
The handling of email messages being routed via an Email Mask is different depending on if the real email address is Internal (i.e. A Sudo Platform email address), or External (Gmail, Yahoo, etc).
Internal Email Masks
An Internal Email Mask allows the user to freely send and receive messages via their Mask, without exposing the real email address to other participants in the email chain.
Inbound Message Receiving
When the Sudo Platform Email Service receives an email message that has been sent to an Email Mask with an Internal real email address, it processes it much the same as it would for an email sent directly to the real email address. It will be placed in the INBOX of the real email address, but 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 using their Email Mask with an Internal real email address. To do this, call 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 Sending & Receiving Email for more detail
// Collect the input headers, body, attachments and sender email mask id // however makes sense for your implementation.constsenderEmailMaskId:string=emailMask.idconstemailMessageHeader:InternetMessageFormatHeader={from:{emailAddress:"[email protected]"},// Must match emailMask.maskAddressto: [{emailAddress:"[email protected]"}],cc: [{emailAddress:"[email protected]"}],bcc: [{emailAddress:"[email protected]"}],replyTo: [{emailAddress:"[email protected]"}],subject:"Example subject line",}constemailAttachment:EmailAttachment={filename:"fooAttachment.pdf",contentId:uuid.v4(),mimeType:"application/pdf",inlineAttachment:false,data:// ... Some pdf data}constinlineAttachment:EmailAttachment={filename:"fooImage.png",contentId:uuid.v4(),mimeType:"image/png",inlineAttachment:true,data:// ... Some image data}try{constinput:SendMaskedEmailMessageInput={senderEmailMaskId:senderEmailMaskId,emailMessageHeaders:emailMessageHeader,body:"An example email body",attachments: [emailAttachment],inlineAttachments: [inlineAttachment],}constresult=awaitemailClient.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 }
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 address.
For the following example, assume the following:
The domain set up for Email Masks in the service is mask.sudoplatform.com
When a message is received that has been sent to [email protected] from [email protected], the Sudo Platform Email Service makes the following changes to the message headers before forwarding the message to [email protected]:
The service will then forward the message to [email protected] 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 reply flow. The message will be sent to [email protected] , 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 [email protected] to send an email to [email protected] without having received one first.
Continuing with the above example, when a message is received that has been sent to [email protected], from [email protected], 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 service will also make an effort to remove any other headers that may contain [email protected] . The message is then forwarded to [email protected] .
/// 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: "[email protected]"), // Must match emailMask.maskAddress
to: [EmailAddressDetail(emailAddress: "[email protected]")],
cc: [EmailAddressDetail(emailAddress: "[email protected]")],
bcc: [EmailAddressDetail(emailAddress: "[email protected]")],
replyTo: [EmailAddressDetail(emailAddress: "[email protected]")],
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
}
// 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("[email protected]"), // Must match emailMask.maskAddress
to = listOf(EmailMessage.EmailAddress("[email protected]")),
cc = listOf(EmailMessage.EmailAddress("[email protected]")),
bcc = listOf(EmailMessage.EmailAddress("[email protected]")),
replyTo = listOf(EmailMessage.EmailAddress("[email protected]")),
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
}
}
