Search…
Manage Email Addresses
Provides the essentials to give your users their own email address with the privacy and security benefits of a Sudo
Email addresses are a core component of the Email SDK. Addresses for different configured domains can be provisioned and used to communicate with other recipients.
Provisioning an email address is a two-step process. First, a check should be performed to determine if the email address is valid and available. Once results are returned and the desired address is selected, the address can be provisioned to a Sudo.

Get Supported Email Domains

When provisioning a new email address for your user, a domain is needed to ensure the email address will be valid. The Sudo Platform email service can be configured to support issuing email addresses for multiple domains.
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.
A call to the getSupportedEmailDomains method provides a list of supported domains for provisioning an email address.
It is required that CachePolicy set to RemoteOnly be used before CacheOnly for at least one successful call to the service.
TypeScript
Swift
Kotlin
1
try {
2
const domains = await emailClient.getSupportedEmailDomains(
3
CachePolicy.RemoteOnly
4
)
5
// `domains` contains a list of supported domains to be used for email address provisioning.
6
} catch {
7
// Handle/notify user of errors
8
}
Copied!
1
emailClient.getSupportedDomainsWithCachePolicy(.remoteOnly) { result in
2
switch result {
3
case let .failure(cause):
4
// Handle/notify user of error
5
case let .success(domains):
6
// `domains` contains an array of supported domains to be used for email address provisioning.
7
}
Copied!
1
launch {
2
try {
3
val domains = withContext(Dispatchers.IO) {
4
emailClient.getSupportedEmailDomains(CachePolicy.REMOTE_ONLY)
5
}
6
// [domains] contains a list of supported domains to be used for email address provisioning.
7
} catch (e: EmailAddressException) {
8
// Handle/notify user of exception
9
}
10
}
Copied!

Check Email Address Availability

When choosing a unique email address, it is important to give your user feedback as to whether the email address they are attempting to provision is valid or not. This is achieved by using the checkEmailAddressAvailability method.
The first input property, localParts, takes in a set of local parts to validate and check if they are available. If any of the local parts are invalid or the input contains more than five local parts to check, an invalid argument error will be returned.
The second input property, domains, should be a set of email domains exclusively supported by the email service. It is recommended to use the getSupportedEmailDomains method to retrieve this set. If an unsupported domain is supplied, an invalid email domain error will be returned.
TypeScript
Swift
Kotlin
1
try {
2
const localParts = Set(['johndoe', 'jane.citizen'])
3
const domains = await emailClient.getSupportedEmailDomains(
4
CachePolicy.RemoteOnly
5
)
6
const emailAddresses = await emailClient.checkEmailAddressAvailability({
7
localParts,
8
domains,
9
})
10
// For example, if the domains list is:
11
// [
12
// "example.com",
13
// "sudoplatform.com"
14
// ]
15
// And all emails are available for both domains, this would return a result
16
// that looks like this:
17
// [
22
// ]
23
} catch {
24
// Handle/notify user of errors
25
}
Copied!
1
let localParts = ["johndoe", "jane.citizen"]
2
/// In reality, this would be a subset of the result of `getSupportedDomains`.
3
let supportedDomains = ["example.com", "sudoplatform.com"]
4
emailClient.checkEmailAddressAvailabilityWithLocalParts(
5
localParts,
6
domains: supportedDomains
7
) { result in
8
switch result {
9
case let .failure(error):
10
/// Handle/notify user of error
11
case let .success(emailAddresses):
12
/// If all emails were available for both domains, this would return a result that looks like this:
13
/// [
18
/// ]
19
}
Copied!
1
launch {
2
try {
3
val localParts = listOf("johndoe", "jane.citizen")
4
val supportedDomains = emailClient.getSupportedEmailDomains()
5
val emailAddresses = emailClient.checkEmailAddressAvailability(
6
localParts = localParts,
7
domains = supportedDomains
8
)
9
// If all emails are available for both domains,
10
// this would return a result that looks like this:
11
// [
16
// ]
17
} catch (e: EmailAddressException) {
18
// Handle/notify user of error
19
}
20
}
Copied!
All email addresses will be lower-cased in the return result. For example a local part input of JoHnDoE would be returned as johndoe....

Provision Email Address

Once an available email address has been found, it can be used to provision a valid email address for a Sudo. An email address can be provisioned by calling the provisionEmailAddress method and will return the newly provisioned email address object.
The input email address must be valid and available, so it is highly recommended that you use the Check Email Address Availability API to validate the email address first.
An ownershipProofToken is required as part of the input. This ties together the Sudo and email address such that the Sudo becomes the owner of the email address. Use the getOwnershipProof method on the SudoProfilesClient in the Sudo Profiles SDK in order to obtain an ownershipProofToken. See the Sudo section for more information.
An optional alias can also be provided as part of the input to provision an email address. The alias can be updated after initially provisioning the email address as discussed in the Updating Metadata of an Email Address section.
When an email address is provisioned, a set of standard email folders is also created and associated with the newly provisioned email address. Find out more about managing email folders here.
TypeScript
Swift
Kotlin
1
const emailAddressInput: string = // Found via the check email address availability API
2
const ownershipProofToken: string = // Found via the get ownership proof API (See "Sudos" section)
3
try {
4
const emailAddress = await emailClient.provisionEmailAddress({
5
emailAddressInput,
6
ownershipProofToken,
7
alias: 'John Smith' // Optionally supply an alias
8
})
9
} catch {
10
// Handle/notify user of errors
11
}
Copied!
1
/// Collect the input email address and sudo id however makes sense for your implementation.
2
let emailAddress = self.input.emailAddress
3
let sudoId = self.input.sudoId
4
emailClient.provisionEmailAddress(emailAddress, sudoId: sudoId) { result in
5
switch result {
6
case let .failure(cause):
7
/// Handle/notify user of error
8
case let .success(provisionedEmailAddress):
9
/// `provisionedEmailAddress` contains the newly provisioned email address.
10
}
Copied!
1
// val sudo: Sudo
2
// val emailAddressInput: String // Found via the check email address availability API
3
launch {
4
try {
5
val emailAddress = withContext(Dispatchers.IO) {
6
emailClient.provisionEmailAddress(emailAddressInput, sudo.id)
7
}
8
// The returned [emailAddress] has been provisioned
9
} catch (e: EmailAddressException) {
10
// Handle/notify user of exception
11
}
12
}
Copied!

Entitlements

In order to be able to provision an email address, the user must be entitled. To provision an email address the following entitlement checks are performed:
    1.
    The user must not have more Sudo Profiles than permitted by their sudoplatform.sudo.max entitlement.
    2.
    The user is entitled to provision email addresses by the sudoplatform.email.provisionEmailUserEntitled entitlement.
    3.
    The Sudo Profile against which the new email address is to be provisioned has at least 1 remaining sudoplatform.email.maxEmailAddressesPerSudo entitlement to consume.
If these entitlements checks do not succeed, the provisionEmailAddress API fails with an insufficient entitlements error.
See Email Entitlements for an overview of how the Email service integrates with the Sudo Platform Entitlements system.
In order to be able to provision an email address, the user must be entitled. To provision an email address the following entitlement checks are performed:
    1.
    The user must not have more Sudo Profiles than permitted by their sudoplatform.sudo.max entitlement.
    2.
    The user is entitled to provision email addresses by the sudoplatform.email.provisionEmailUserEntitled entitlement.
    3.
    The Sudo Profile against which the new email address is to be provisioned has at least 1 remaining sudoplatform.email.maxEmailAddressesPerSudo entitlement to consume.
If these entitlements' checks do not succeed, the provisionEmailAddress API fails with an insufficient entitlements error.
See Email Entitlements for an overview of how the Email service integrates with the Sudo Platform Entitlements system.

Deprovision Email Address

An email address can be deprovisioned using the deprovisionEmailAddress method by passing in the id of an existing email address object. The email address object that was deprovisioned will be returned and will no longer be usable for provisioning another email address.
By deprovisioning the email address, the user's address and all associated user data including messages and folders will be deleted; the email address will no longer be usable. The deprovisioned address will also be held indefinitely and be blocked for re-use from a subsequent provision call.
TypeScript
Swift
Kotlin
1
// Collect the input email address id however makes sense for your implementation.
2
const emailAddressId = emailAddress.id
3
try {
4
const emailAddress = await emailClient.deprovisionEmailAddress(
5
emailAddressId
6
)
7
// The returned `emailAddress` has now been deprovisioned.
8
} catch {
9
// Handle/notify user of errors
10
}
Copied!
1
/// Collect the input email address id however makes sense for your implementation.
2
let provisionedEmailAddressId = self.input.emailAddressId
3
emailClient.deprovisionEmailAddressWithId(provisionedEmailAddressId) { result in
4
switch result {
5
case let .failure(cause):
6
/// Handle/notify user of error
7
case let .success(deprovisionedEmailAddress):
8
/// `deprovisionedEmailAddress` is the record that was just deprovisioned.
9
}
Copied!
1
// Collect the input email address id however makes sense for your implementation.
2
// val emailAddressId = emailAddress.id
3
launch {
4
try {
5
val emailAddress = withContext(Dispatchers.IO) {
6
emailClient.deprovisionEmailAddress(emailAddressId)
7
}
8
// The returned [emailAddress] has now been deprovisioned.
9
} catch (e: EmailAddressException) {
10
// Handle/notify user of exception
11
}
12
}
Copied!

Updating Metadata of an Email Address

The metadata of an email address object can be updated by calling the updateEmailAddressMetadata method. Currently, the only attribute that can be updated on an email address object is the alias. The alias is an encrypted optional attribute on the email address object which can be modified by the user.
TypeScript
Swift
Kotlin
1
// Collect the input email address id however makes sense for your implementation.
2
try {
3
const id = await emailClient.updateEmailAddressMetadata({
4
id,
5
values: { alias: 'John Smith' },
6
})
7
// `id` contains the identifier of the newly updated email address object.
8
} catch {
9
// Handle/notify user of errors
10
}
Copied!
1
Coming Soon!
Copied!
1
Coming Soon!
Copied!

Retrieving Existing Email Addresses

Previously provisioned email addresses can be accessed in two ways: via its identifier (Single Email Address by Id), or via a broad multi access method (Multiple Provisioned Email Addresses).
If an email address has been provisioned and then deprovisioned, it will no longer be available via the methods discussed in this section.
A fetch of single or multiple email addresses can be performed remotely or locally by specifying the appropriate CachePolicy as part of the input.

Single Email Address by Id

To retrieve a single email address given its unique id, use the getEmailAddress method. This method will return the record if it exists.
TypeScript
Swift
Kotlin
1
try {
2
const emailAddress = await emailClient.getEmailAddress({
3
id,
4
cachePolicy: CachePolicy.RemoteOnly,
5
})
6
// `emailAddress` contains the email address object, else `undefined` if not found.
7
} catch {
8
// Handle/notify user of errors
9
}
Copied!
1
/// Collect the input address of the email address object.
2
let emailAddressId = input.address
3
emailClient.getEmailAddressWithId(emailAddressId, cachePolicy: .remoteOnly) { result in
4
switch result {
5
case let .failure(cause):
6
/// Handle/notify user of error
7
case let .success(emailAddress):
8
/// `emailAddress` contains the email address object, else `nil` if not found.
Copied!
1
launch {
2
try {
3
val emailAddress = withContext(Dispatchers.IO) {
4
emailClient.getEmailAddress(
5
id,
6
cachePolicy = CachePolicy.REMOTE_ONLY
7
)
8
}
9
// [emailAddress] contains the email address object, else [nil] if not found.
10
} catch (e: EmailAddressException) {
11
// Handle/notify user of exception
12
}
13
}
Copied!

Multiple Provisioned Email Addresses

The ability to retrieve multiple or all email addresses available to the user is supported. These results can be paginated and filtered. Provide an EmailAddressFilter input property to the list API call to filter the results.
A call to a list API will return a ListEmailAddressesResult with a status and depending on the status, a list of matching items and a nextToken to support pagination. If no results matching the input are found, the result will contain empty items. There can be three possible statuses returned:
Status
Definition
Success
A list of all requested email addresses are returned.
Partial
A list of all email addresses that were successfully fetched and unencrypted are returned as well as a list of all email addresses that failed to unencrypt successfully, including an error indicating the reason for the failure.
Failure
All email addresses failed to be fetched or unencrypted. Contains an error indicating the reason for the failure.
An email address may fail to be unencrypted if the version of the client is not up-to-date or if the required cryptographic key is missing from the client device.

All Provisioned Email Addresses

To retrieve multiple email addresses that are owned by the signed in user, call the listEmailAddresses method.
TypeScript
Swift
Kotlin
1
try {
2
const result = await emailClient.listEmailAddresses({
3
filter: { emailAddress: { beginsWith: 'foobar' } },
4
cachePolicy: CachePolicy.RemoteOnly,
5
limit: 20,
6
nextToken,
7
})
8
if (result.status === ListOperationResultStatus.Success) {
9
// `result` contains the list of items matching the input.
10
// Page through the results if result.nextToken != undefined.
11
}
12
} catch {
13
// Handle/notify user of errors
14
}
Copied!
1
emailClient.listEmailAddressesWithSudoId(nil, filter: nil, limit: nil, nextToken: nil) { result in
2
switch result {
3
case let .failure(cause):
4
/// Handle/notify user of error
5
case let .success(output):
6
/// `output` contains a `ListOutput` item of results matching the call.
7
}
Copied!
1
launch {
2
try {
3
val emailAddresses = withContext(Dispatchers.IO) {
4
emailClient.listEmailAddresses(
5
sudoId = null,
6
filterEmailAddressesBy {
7
address beginsWith "fooBar"
8
}
9
limit = 20,
10
nextToken = nextToken,
11
cachePolicy = CachePolicy.REMOTE_ONLY
12
)
13
}
14
// [emailAddresses] contains the email addresses that match the input.
15
} catch (e: EmailAddressException) {
16
// Handle/notify user of exception
17
}
18
}}
Copied!
All Provisioned Email Addresses for a Sudo
To retrieve multiple email addresses that are owner by a particular Sudo, call the **listEmailAddressesForSudoId method by passing in the id of the Sudo to query.
TypeScript
Swift
Kotlin
1
// Collect the input sudo id however makes sense for your implementation.
2
const sudoId = sudo.id
3
try {
4
const result = await emailClient.listEmailAddressesForSudoId({
5
sudoId,
6
filter: { emailAddress: { beginsWith: 'foobar' } },
7
cachePolicy: CachePolicy.RemoteOnly,
8
limit: 20,
9
nextToken,
10
})
11
if (result.status === ListOperationResultStatus.Success) {
12
// `result` contains the list of items matching the input.
13
// Page through the results if result.nextToken != undefined.
14
}
15
} catch {
16
// Handle/notify user of errors
17
}
Copied!
1
Coming Soon!
Copied!
1
Coming Soon!
Copied!
For the best performance depending on your use case, look up email addresses by Sudo instead of looking up all email addresses and applying a filter.
By default, list email addresses API have a limit of 1MB of data when no limit is supplied. If using a filter, the limit is applied before the filter.

Filtering Email Addresses

Email address queries can be filtered in multiple ways. Email addresses can be filtered by the following properties:
    id
    emailAddress
    size
    unseenCount
For example, if the user wished to lookup email addresses and filter out all email addresses that have the emailAddress [email protected], they could provide a filter for an email address that does not equal the string.
Email address filters also support more complex logic, such as not, and and or. These are equivalent to their logical names and allow for stringing together complex logic. An example may consist of using an or filter with two filters nested: emailAddress not equals [email protected], emailAddress not equals [email protected]. This filter will ensure that the results that are returned contain all the addresses that do not equal [email protected] or [email protected].
TypeScript
Swift
Kotlin
1
try {
2
const result = await emailClient.listEmailAddresses({
3
filter: {
4
or: [
5
{ emailAddress: { ne: '[email protected]' } },
6
{ emailAddress: { ne: '[email protected]' } },
7
],
8
},
9
cachePolicy: CachePolicy.RemoteOnly,
10
limit: 20,
11
nextToken,
12
})
13
if (result.status === ListOperationResultStatus.Success) {
14
// `result` contains the list of items matching the input.
15
// Page through the results if result.nextToken != undefined.
16
}
17
} catch {
18
// Handle/notify user of errors
19
}
Copied!
1
Coming Soon!
Copied!
1
Coming Soon!
Copied!
Last modified 21d ago