> For the complete documentation index, see [llms.txt](https://docs.sudoplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sudoplatform.com/guides/email/email-aliases/managing-email-aliases.md).

# Managing Email Aliases

Give your users the ability to secure their real email addresses behind Email Aliases.

**Email Aliases** can be provisioned for different configured domains to provide more options to your users. To provision an Email Alias the sequence is:

1. Retrieve the list of available domains
2. Check if the desired alias address for a given domain is valid and available
3. Provision the Email Alias address

### Get Email Alias Domains

The Sudo Platform Email Service can be configured to support multiple domains for your email aliasing needs.

{% hint style="info" %}
Each project in your Sudo Platform account can be configured to support a set of email domains. Your solutions engineer can assist you in configuring DNS entries for domains you own or you can have the Sudo Platform do that on your behalf.
{% endhint %}

A call to the `listEmailDomains` method provides the configured domains along with metadata about each one. To find the domains that are available for provisioning Email Aliases, filter the results where `isAliasDomain == true`.

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

```typescript
try {
    const domains = await emailClient.listEmailDomains()
    const aliasDomains = domains.filter(d => d.isAliasDomain)
    // `aliasDomains` contains an array of supported domains to be used for provisioning Email Aliases
} catch (e) {
    // Handle/notify user of errors
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
do {
    let domains = try await client.listEmailDomains()
    let aliasDomains = domains.filter { $0.isAliasDomain }
    // `aliasDomains` contains a list of domains available for provisioning Email Aliases
} catch {
    /// Handle/notify user of errors
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
launch {
    try {
        val domains = withContext(Dispatchers.IO) {
            emailClient.listEmailDomains()
        }
        val aliasDomains = domains.filter { it.isAliasDomain }
        // [aliasDomains] contains a list of configured domains for provisioning Email Aliases.
    } catch (e: EmailAddressException) {
        // Handle/notify user of exception
    }
 }
```

{% endtab %}
{% endtabs %}

### Check Email Alias Availability

In order to ensure your users can choose a unique, available, address for their Email Alias, you can use the same `checkEmailAddressAvailability` method as you would for a regular Sudo Platform email address. More information on that method can be found [here](https://docs.sudoplatform.com/guides/email/manage-email-addresses#check-email-address-availability).

### Provision Email Alias

Once your user has the address they would like to use for their Email Alias, it can be provisioned. The `provisionEmailAlias` method will return the newly provisioned Email Alias object.

An `ownershipProofToken` is required as part of the input. This ties together the Sudo and Email Alias such that the Sudo becomes the owner of the Alias. Use the `getOwnershipProof` method on the `SudoProfilesClient` in the **Sudo** **Profiles SDK** in order to obtain an `ownershipProofToken`. See the [Sudo](https://docs.sudoplatform.com/guides/sudos) section for more information.

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

```typescript
const aliasAddress: string = // The email address to use for the Alias, checked via the checkEmailAddressAvailability method
const ownershipProofToken: string = // Found via the get ownership proof API (See "Sudos" section)
const realAddress: string = // The real email address that the Alias will forward to
try {
    const emailAlias = await emailClient.provisionEmailAlias({
        aliasAddress,
        realAddress,
        ownershipProofToken,
    })
} catch (e) {
    // Handle/notify user of errors 
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
let aliasAddress: String = /// The email address to use for the Alias, checked via the checkEmailAddressAvailability method
let ownershipProofToken: String = /// Found via the get ownership proof API (See "Sudos" section)
let realAddress: String = /// The real email address that the Alias will forward to
do {
    let provisionEmailAliasInput = ProvisionEmailAliasInput(
        aliasAddress: aliasAddress,
        ownershipProofToken: ownershipProofToken,
        realAddress: realAddress
    )
    let emailAlias = try await emailClient.provisionEmailAlias(
        withInput: provisionEmailAliasInput
    )
    /// `emailAlias` contains the newly provisioned Email Alias
} catch {
    /// Handle/notify user of error
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val aliasAddress: String = /// The email address to use for the Alias, checked via the checkEmailAddressAvailability method
val ownershipProofToken: String = /// Found via the get ownership proof API (See "Sudos" section)
val realAddress: String = /// The real email address that the Alias will forward to
launch {
    try {
        val input = ProvisionEmailAliasInput(
            aliasAddress = aliasAddress,
            ownershipProofToken = ownershipProofToken,
            realAddress = realAddress,
        )
        val emailAlias = withContext(Dispatchers.IO) {
            emailClient.provisionEmailAlias(input)
        }
        // The returned [emailAlias] has been provisioned
    } catch (e: EmailAddressException) {
        // Handle/notify user of exception
    }
}
```

{% endtab %}
{% endtabs %}

#### Verify Real Address Ownership

The `realAddress` property of the input must be the exact `local-part@domain` email address that the alias should forward to. For Sudo Platform Email Addresses, the address must be owned by the same user trying to provision the Alias.

If your use case requires to allow your users to set up Aliases for external email addresses, then the Alias that is provisioned will initially have its `state` set to `PENDING`. While in this state, it cannot receive messages. In order to change the `state` to `ENABLED`, the user must verify ownership of their external email address. See [Verifying External Email Addresses](https://docs.sudoplatform.com/guides/email/email-aliases/verifying-external-email-addresses.md).

#### Entitlements <a href="#entitlements" id="entitlements"></a>

In order to be able to provision an Email Alias, the user must be entitled. The following entitlement checks are performed:

1. The user is entitled to provision Email Aliases by the `sudoplatform.email.emailAliasUserEntitled` entitlement.
2. The user against which the new email address is to be provisioned has at least 1 remaining `sudoplatform.email.emailAliasMaxPerUser` entitlement to consume.

If these entitlements' checks do not succeed, the `provisionEmailAlias` API fails with an insufficient entitlements error.

{% hint style="info" %}
See [Email Entitlements](https://docs.sudoplatform.com/guides/email/email-entitlements) for an overview of how the Email service integrates with the Sudo Platform Entitlements system.
{% endhint %}

#### Optional Parameters

The `provisionEmailAlias` method's input object can take up to two additional optional parameters:

1. `expiresAt` - If set, the alias will automatically be deprovisioned at the given date.
2. `metadata` - This is a string to string map that can be used to store information about the Email Alias such as the purpose of it. The data in this property gets encrypted with the user's default key pair before being sent to the server, and decrypted upon retrieval.

Both of these optional properties can be updated, or deleted via the `updateEmailAlias` method.

### Deprovision Email Alias

An Email Alias can be deprovisioned using the `deprovisionEmailAlias` method by passing in the `id` of an existing Email Alias object.

{% hint style="warning" %}
By deprovisioning an Email Alias, the user will no longer receive messages sent to that Alias, and a bounce will be returned to anyone sending messages to it.
{% endhint %}

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

```typescript
const emailAliasId: string = emailAlias.id // Collect the Email Alias however makes sense for your application
try {
    const deprovisionedEmailAlias = await emailClient.deprovisionEmailAlias({
        emailAliasId: emailAliasId
    })
} catch (e) {
    // Handle/notify user of errors 
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
/// Collect the input email alias id however makes sense for your implementation.
let emailAliasId = emailAlias.id
do {
    let deprovisionEmailAliasInput = DeprovisionEmailAliasInput(
        emailAliasId: emailAliasId
    )
    let deprovisionedEmailAlias = try await emailClient.deprovisionEmailAlias(
        withInput: deprovisionEmailAliasInput
    )
    /// `deprovisionedEmailAlias` is the record that was just deprovisioned.
} catch {
    /// Handle/notify user of error
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
/// Collect the input email alias id however makes sense for your implementation.
val emailAliasId = emailAlias.id
launch {
    try {
        val input = DeprovisionEmailAliasInput(
            emailAliasId = emailAliasId
        )
        val emailAlias = withContext(Dispatchers.IO) {
            emailClient.deprovisionEmailAlias(input)
        }
        // The returned [emailAlias] has been deprovisioned
    } catch (e: EmailAddressException) {
        // Handle/notify user of exception
    }
}
```

{% endtab %}
{% endtabs %}

### Updating an Email Alias

An existing email alias can have a subset of its data updated by the user by calling the `updateEmailAlias` method. The properties that can be updated are outlined in the table below.

<table><thead><tr><th width="124.50390625">Property</th><th width="339.94921875">To ignore</th><th>To delete</th><th>Notes</th></tr></thead><tbody><tr><td>expiresAt</td><td>TypeScript: <code>undefined</code> (or exclude from object)<br>Swift: <code>nil</code><br>Kotlin: <code>null</code></td><td>Typescript: <code>null</code><br>Swift: <code>Date(timeIntervalSince1970: 0)</code><br>Kotlin: <code>Date(0)</code></td><td></td></tr><tr><td>metadata</td><td>TypeScript: <code>undefined</code> (or exclude from object)<br>Swift: <code>nil</code><br>Kotlin: <code>null</code></td><td>Typescript: <code>null</code><br>Swift: <code>[:]</code><br>Kotlin: <code>emptyMap()</code></td><td></td></tr><tr><td>realAddress</td><td>TypeScript: <code>undefined</code> (or exclude from object)<br>Swift: <code>nil</code><br>Kotlin: <code>null</code></td><td>N/A</td><td>This property can <strong>only</strong> be updated for Email Aliases with an external real address that have not yet been <a href="https://docs.sudoplatform.com/guides/email/email-aliases/verifying-external-email-addresses.md">verified</a>.</td></tr></tbody></table>

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

```typescript
const emailAliasId: string = emailAlias.id // Collect the Email Alias however makes sense for your application
try {
    const metadata = { prop1: 'abc', prop2: 123 }
    const expiresAt = new Date() // Construct the expiry date however makes sense
    const realAddress = "" // Used to update the realAddress if a user input it incorrectly
    let updatedAlias = await emailClient.updateEmailAlias({
        emailAliasId: emailAliasId,
        metadata: metadata,
        expiresAt: expiresAt,
        realAddress: realAddress,
    })
    // The Email Alias now has the updated properties
    
    updatedAlias = await emailClient.updateEmailAlias({
        emailAliasId: emailAliasId,
        metadata: null,
        expiresAt: null,
    })
    // The Email Alias no longer has the `metadata` or `expiresAt` set
} catch (e) {
    // Handle/notify user of errors 
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
// Collect the input email alias id however makes sense for your implementation.
let emailAliasId = emailAlias.id
do {
    let metadata = [ "prop1": "abc", "prop2": String(123) ]
    let expiresAt = Date() /// Construct the expiry date however makes sense
    let realAddress = "" // Used to update the realAddress if a user input it incorrectly
    var input = UpdateEmailAliasInput(
        emailAliasId: emailAliasId,
        metadata: metadata,
        expiresAt: expiresAt,
        realAddress: realAddress
    )
    var updatedAlias = try await emailClient.updateEmailAlias(withInput: input)
    // The Email Alias now contains the updated properties
    
    input = UpdateEmailAliasInput(
        emailAliasId: emailAliasId,
        metadata: [:],
        expiresAt: Date(timeIntervalSince1970: 0)
    )
    updatedAlias = try await emailClient.updateEmailAlias(withInput: input)
    // The Email Alias no longer has metadata or expiresAt
} catch {
    /// Handle/notify user of error
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
/// Collect the input email alias id however makes sense for your implementation.
val emailAliasId = emailAlias.id
launch {
    try {
        val metadata = mapOf(
            "prop1" to "abc",
            "prop2" to "${123}"
        )
        val expiresAt = Date() // Construct the expiry date however makes sense
        val realAddress = "" // Used to update the realAddress if a user input it incorrectly
        val input = UpdateEmailAliasInput(
            emailAliasId = emailAliasId,
            metadata = metadata,
            expiresAt = expiresAt,
            realAddress = realAddress
        )
        val updatedAlias = withContext(Dispatchers.IO) {
            emailClient.updateEmailAlias(input)
        }
        // The Email Alias now contains the updated properties
        
        input = UpdateEmailAliasInput(
            emailAliasId = emailAliasId,
            metadata = emptyMap(),
            expiresAt = Date(0)
        )
        updatedAlias = withContext(Dispatchers.IO) {
            emailClient.updateEmailAlias(input)
        }
        // The Email Alias no longer has metadata or expiresAt
    } catch (e: EmailAddressException) {
        // Handle/notify user of exception
    }
}
```

{% endtab %}
{% endtabs %}

### Retrieving Existing Email Aliases

Previously provisioned Email Aliases can be retrieved as a paginated list via the `listEmailAliasesForOwner` method.

A call to the API will return a `ListOutput<EmailAlias>` object. The `items` property will contain a list of the aliases and the `nextToken` property will contain a token that can be used for retrieving the next page of results if there are more.

The list can also be filtered by passing in an optional `filter` property to the method call. The call can be filtered by `status` and/or `realAddressType`. Each of those must further be specified as either `equal`, `oneOf`, `notEqual` or `notOneOf`.

The list can also be given a `limit` on how many results to return. By default, this limit is 10.

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

```typescript
const emailAliasId: string = emailAlias.id // Collect the Email Alias however makes sense for your application
try {
    const result = await emailClient.listEmailAliasesForOwner({
        filter: {
            status: { notOneOf: [EmailAliasStatus.PENDING, EmailAliasStatus.LOCKED] },
            realAddressType: { equal: EmailAliasRealAddressType.INTERNAL },
        }
    }
    // `result.items` contains a list of Aliases that are not PENDING or LOCKED and have a real
    // address type of INTERNAL
    // Page through the results if result.nextToken != undefined.
} catch (e) {
    // Handle/notify user of errors 
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
// Collect the input email alias id however makes sense for your implementation.
let emailAliasId = emailAlias.id
do {
    let filter = EmailAliasFilter(
        status: .notOneOf([.pending, .locked]),
        realAddressType: .equal(.internal),
    )
    let input = ListEmailAliasesForOwnerInput(
        filter: filter
    )
    let result = try await emailClient.listEmailAliasesForOwner(withInput: input)
    // `result.items` contains a list of Aliases that are not PENDING or LOCKED and have a real
    // address type of INTERNAL
    // Page through the results if result.nextToken != nil.
} catch {
    /// Handle/notify user of error
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
/// Collect the input email alias id however makes sense for your implementation.
val emailAliasId = emailAlias.id
launch {
    try {
        val filter = EmailAliasFilterInput(
            status = NotOneOfStatusFilter(
                listOf(EmailAliasStatus.PENDING, EmailAliasStatus.LOCKED)
            ),
            realAddressType = EqualRealAddressTypeFilter(EmailAliasRealAddressType.INTERNAL)
        )
        val input = ListEmailAliasesForOwnerInput(filter = filter)
        val result = withContext(Dispatchers.IO) { 
            emailClient.listEmailAliasesForOwner(input)
        }
        // `result.items` contains a list of Aliases that are not PENDING or LOCKED and have a real
        // address type of INTERNAL
        // Page through the results if result.nextToken != null.
    } catch (e: EmailAddressException) {
        // Handle/notify user of exception
    }
}
```

{% endtab %}
{% endtabs %}

### Disabling and Enabling Email Aliases

An Email Alias can be disabled by the user to temporarily stop it from receiving emails without fully deprovisioning it. While in the `DISABLED` state, messages sent to the alias will not be delivered to the real address, and the sender will **not** receive a bounce in response until it is enabled again.

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

```typescript
const emailAliasId: string = emailAlias.id // Collect the Email Alias however makes sense for your application
try {
    const disabledAlias = await emailClient.disableEmailAlias({
        emailAliasId: emailAliasId,
    })
    // Alias is now disabled; disabledAlias.status == EmailAliasStatus.DISABLED
    
    const enabledAlias = await emailClient.enableEmailAlias({
        emailAliasId: emailAliasId,
    })
    // Alias is now enabled; enabledAlias.status == EmailAliasStatus.ENABLED
} catch (e) {
    // Handle/notify user of errors 
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
// Collect the input email alias id however makes sense for your implementation.
let emailAliasId = emailAlias.id
do {
    let disableInput = DisableEmailAliasInput(emailAliasId: emailAliasId)
    let disabledAlias = try await client.disableEmailAlias(withInput: disableInput)
    /// Email Alias is now disabled; disabledAlias.status == .disabled
    
    let enableInput = EnableEmailAliasInput(emailAliasId: emailAliasId)
    let enabledAlias = try await client.enableEmailAlias(withInput: enableInput)
    /// Email Alias is now enabled; disabledAlias.status == .enabled
} catch {
    /// Handle/notify user of error
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
/// Collect the input email alias id however makes sense for your implementation.
val emailAliasId = emailAlias.id
launch {
    try {
        val disableInput = DisableEmailAliasInput(emailAliasId)
        val disabledAlias = withContext(Dispatchers.IO) {
            emailClient.disableEmailAlias(disableInput)
        }
        // Email Alias is now disabled; disabledAlias.status == EmailAliasStatus.DISABLED
        
        val enableInput = EnableEmailAliasInput(emailAliasId)
        val enabledAlias = withContext(Dispatchers.IO) {
            emailClient.enableEmailAlias(disableInput)
        }
        // Email Alias is now enabled; disabledAlias.status == EmailAliasStatus.ENABLED
    } catch (e: EmailAddressException) {
        // Handle/notify user of exception
    }
}
```

{% endtab %}
{% endtabs %}
