# Sending & Receiving Messages

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](https://docs.sudoplatform.com/guides/send-an-email#receiving-email-messages "mention")

#### 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 [send-an-email](https://docs.sudoplatform.com/guides/email/send-an-email "mention") for more detail

{% tabs %}
{% tab title="TypeScript" %}

```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: "from@bar.com" }, // Must match emailMask.maskAddress
    to: [{ emailAddress: "to@bar.com" }],
    cc: [{ emailAddress: "cc@bar.com" }],
    bcc: [{ emailAddress: "bcc@bar.com" }],
    replyTo: [{ emailAddress: "replyTo@bar.com" }],
    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 
}

```

{% endtab %}

{% tab title="Swift" %}

```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: "from@bar.com"), // Must match emailMask.maskAddress
    to: [EmailAddressDetail(emailAddress: "to@bar.com")],
    cc: [EmailAddressDetail(emailAddress: "cc@bar.com")],
    bcc: [EmailAddressDetail(emailAddress: "bcc@bar.com")],
    replyTo: [EmailAddressDetail(emailAddress: "replyTo@bar.com")],
    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
}
```

{% endtab %}

{% tab title="Kotlin" %}

```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("from@bar.com"), // Must match emailMask.maskAddress
    to = listOf(EmailMessage.EmailAddress("to@bar.com")),
    cc = listOf(EmailMessage.EmailAddress("cc@bar.com")),
    bcc = listOf(EmailMessage.EmailAddress("bcc@bar.com")),
    replyTo = listOf(EmailMessage.EmailAddress("replyTo@bar.com")),
    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
    }
}
```

{% endtab %}
{% endtabs %}

### 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`
* Email Mask
  * Mask address: `superman@mask.sudoplatform.com`
  * Real external address: `clark.kent@example.com`
* Sender's address: `lex.luthor@example.com`

When a message is received that has been sent to `superman@mask.sudoplatform.com` from `lex.luthor@example.com`, the Sudo Platform Email Service makes the following changes to the message headers before forwarding the message to `clark.kent@example.com`:

* The `From` header is changed to `"lex.luthor@example.com via" <superman@mask.sudoplatform.com>`&#x20;
* The `To` header (or `Cc` if that was used) is changed to `clark.kent@example.com`
* The `Reply-To` header is changed to `replies@mask.sudoplatform.com`

The service will then forward the message to `clark.kent@example.com` 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 `replies@mask.sudoplatform.com` , processed by the Sudo Platform Email Service, and forwarded to the original sender.

{% hint style="info" %}
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 `superman@mask.sudoplatform.com` to send an email to `lois.lane@example.com` without having received one first.
{% endhint %}

Continuing with the above example, when a message is received that has been sent to `replies@mask.sudoplatform.com`, from `clark.kent@example.com`, 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 `superman@mask.sudoplatform.com`
* The `To` header is changed to `lex.luthor@example.com`

The service will also make an effort to remove any other headers that may contain `clark.kent@example.com` . The message is then forwarded to `lex.luthor@example.com` .