Manage Email Address Blocklists

Allow your user to block specific email addresses from being able to send messages to any of their Sudo email addresses

When a user blocks a sender's email address through the Email SDK, that sender is prevented from sending messages to any of the user's email addresses.

Blocking Email Addresses

Email addresses can be blocked in batches and are blocked for all email addresses that the user owns. Blocking addresses can be done through the blockEmailAddresses method by passing in an array of the addresses to be blocked. The addresses should be in the format [e-mail].

The method will respond with a BatchOperationResult type which contains the status of the batch operation. Three possible statuses can be returned:

Status	Definition
Success	All of the email addresses were successfully to blocked.
Partial	Only a subset of the email addresses could be blocked successfully. The return object will include a list of addresses which failed to be blocked and a list of those which succeeded.
Failure	All of the email addresses failed to be blocked.

TypeScript

// Obtain the email addresses to be blocked
const addressesToBlock = arrayOf('[e-mail]', '[e-mail]')
try {
    const blockingResult = await emailClient.blockEmailAddresses({
        addressesToBlock
    })
    switch (blockingResult.status){
        case UpdateEmailMessagesStatus.Success:
          // All addresses were blocked successfully
          break
        case UpdateEmailMessagesStatus.Failed:
          // None of the addresses were blocked successfully
          break
        case UpdateEmailMessagesStatus.Partial:
          // `blockingResult.successItems` contains an array of all the addresses
          // blocked successfully.
          // `blockingResult.failureItems` cotains an array of all the addresses
          // that failed to be blocked successfully.
          break
      }
} catch (e) {
    // Handle/notify user of errors
}  

Swift

// Obtain the email addresses to be blocked
let addresses = ["[e-mail]", "[e-mail]"]
do {
    let blockingResult = try await self.emailClient.blockEmailAddresses(
        addresses: addresses
    )
    switch blockingResult {
        case .success:
            // All addresses were blocked successfully
        case .failure:
            // None of the addresses were blocked successfully
        case .partial:
            // `blokcingResult.successItems` contains an array of all the addresses
            // blocked successfully.
            // `blockingResult.failureItems` cotains an array of all the addresses
            // that failed to be blocked successfully.
    }
} catch {
    // Handle/notify user of error
}

Kotlin

// Obtain the email addresses to be blocked
val addressesToBlock = listOf("[e-mail]", "[e-mail]")
launch {
    try {
        val blockingResult = withContext(Dispatcher.IO) {
            emailClient.blockEmailAddresses(addressesToBlock)
        }
        when (blockingResult) {
            is BatchOperationResult.SuccessOrFailureResult -> {
                // [blockingResult.status] contains the status of the batch block operation.
            }
            is BatchOperationResult.Partial -> {
                // [blockingResult.successValues] contains the list of items for which the block operation succeeded.
                // [blockingResult.failureValues] contains the list of items for which the block operation failed.
            }
        }
    } catch (e: EmailBlocklistException) {
        // Handle/notify user of exception
    }
}

Unblocking Email Addresses

Unblocking email addresses works much the same way as blocking them does. It can be achieved by passing an array of the addresses to be unblocked to the unblockEmailAddresses method. They should also be in the format [e-mail].

The method will respond with the same BatchOperationResult type with the same possible statuses.

Typescript

// Obtain the email addresses to be unblocked
const addressesToUnblock = arrayOf('[e-mail]', '[e-mail]')
try {
    const unblockingResult = await emailClient.unblockEmailAddresses({
        addressesToUnblock
    })
    switch (unblockingResult.status){
        case UpdateEmailMessagesStatus.Success:
          // All addresses were unblocked successfully
          break
        case UpdateEmailMessagesStatus.Failed:
          // None of the addresses were unblocked successfully
          break
        case UpdateEmailMessagesStatus.Partial:
          // `unblockingResult.successItems` contains an array of all the addresses
          // unblocked successfully.
          // `unblockingResult.failureItems` cotains an array of all the addresses
          // that failed to be unblocked successfully.
          break
      }
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the email addresses to be unblocked
let addresses = ["[e-mail]", "[e-mail]"]
do {
    let unblockingResult = try await self.emailClient.unblockEmailAddresses(
        addresses: addresses
    )
    switch unblockingResult {
        case .success:
            // All addresses were unblocked successfully
        case .failure:
            // None of the addresses were unblocked successfully
        case .partial:
            // `unblockingResult.successItems` contains an array of all the addresses
            // unblocked successfully.
            // `unblockingResult.failureItems` cotains an array of all the addresses
            // that failed to be unblocked successfully.
    }
} catch {
    // Handle/notify user of error
}

Kotlin

// Obtain the email addresses to be unblocked
val addressesToUnblock = listOf("[e-mail]", "[e-mail]")
launch {
    try {
        val unblockingResult = withContext(Dispatcher.IO) {
            emailClient.unblockEmailAddresses(addressesToUnblock)
        }
        when (unblockingResult) {
            is BatchOperationResult.SuccessOrFailureResult -> {
                // [unblockingResult.status] contains the status of the batch unblock operation.
            }
            is BatchOperationResult.Partial -> {
                // [unblockingResult.successValues] contains the list of items for which the unblock operation succeeded.
                // [unblockingResult.failureValues] contains the list of items for which the unblock operation failed.
            }
        }
    } catch (e: EmailBlocklistException) {
        // Handle/notify user of exception
    }
}

Alternatively, you can also unblock email addresses by the hashedValue (returned from the getEmailAddressBlocklist endpoint below). This can be useful if the user has lost their cryptographic key and is unable to unseal the plaintext address. The unblockEmailAddressesByHashedValue method works the same way, except it accepts an array of hashedValues instead of plaintext addresses.

Typescript

// Obtain the hashedValues from the getEmailAddressBlocklist endpoint
const hashedValues = arrayOf('hashedValue1', 'hashedValue2')
try {
    const unblockingResult = await emailClient.unblockEmailAddressesByHashedValue({
        hashedValues
    })
    switch (unblockingResult.status){
        case UpdateEmailMessagesStatus.Success:
          // All addresses were unblocked successfully
          break
        case UpdateEmailMessagesStatus.Failed:
          // None of the addresses were unblocked successfully
          break
        case UpdateEmailMessagesStatus.Partial:
          // `unblockingResult.successItems` contains an array of all the addresses
          // unblocked successfully.
          // `unblockingResult.failureItems` cotains an array of all the addresses
          // that failed to be unblocked successfully.
          break
      }
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the hashedValues from the getEmailAddressBlocklist endpoint
let hashedValues = ["hashedValue1", "hashedValue2"]
do {
    let unblockingResult = try await self.emailClient.unblockEmailAddressesByHashedValue(
        hashedValues: hashedValues
    )
    switch unblockingResult {
        case .success:
            // All addresses were unblocked successfully
        case .failure:
            // None of the addresses were unblocked successfully
        case .partial:
            // `unblockingResult.successItems` contains an array of all the addresses
            // unblocked successfully.
            // `unblockingResult.failureItems` cotains an array of all the addresses
            // that failed to be unblocked successfully.
    }
} catch {
    // Handle/notify user of error
}

Kotlin

// Obtain the hashedValues from the getEmailAddressBlocklist endpoint
val hashedValues = listOf("hashedValue1", "hashedValue2")
launch {
    try {
        val unblockingResult = withContext(Dispatcher.IO) {
            emailClient.unblockEmailAddressesByHashedValue(hashedValues)
        }
        when (unblockingResult) {
            is BatchOperationResult.SuccessOrFailureResult -> {
                // [unblockingResult.status] contains the status of the batch unblock operation.
            }
            is BatchOperationResult.Partial -> {
                // [unblockingResult.successValues] contains the list of items for which the unblock operation succeeded.
                // [unblockingResult.failureValues] contains the list of items for which the unblock operation failed.
            }
        }
    } catch (e: EmailBlocklistException) {
        // Handle/notify user of exception
    }
}

Listing Blocked Email Addresses

To obtain a list of blocked email addresses for a user, call the getEmailAddressBlocklist method. It will return an array of UnsealedBlockedAddress objects. They will have three properties:

Property	Description
status	The status of the unsealing operation to access the plaintext address. Possible values are Completed or Failed. If it is Failed there will be an error type indicating the reason for the failure and the address property will contain an empty string.
address	The plaintext version of the blocked address. This will be an empty string if the unsealing process fails.
hashedValue	The unique hash value representing the blocked address. This can be used for unblocking in the event that the plaintext address cannot be unsealed.

Typescript

try {
    const blockedAddresses = await emailClient.getEmailAddressBlocklist()
    // `blockedAddresses` is an array of UnsealedBlockedAddress objects
} catch (e) {
    // Handle/notify user of errors
}

Swift

try {
    let blockedAddresses = try await self.emailClient.getEmailAddressBlocklist()
    // `blockedAddresses` is an array of UnsealedBlockedAddress objects
} catch {
    // Handle/notify user of error
}

Kotlin

launch {
    try {
        val blockedAddresses = withContext(Dispatchers.IO) {
            emailClient.getEmailAddressBlocklist()
        }
        // `blockedAddresses` is an array of of UnsealedBlockedAddress objects
    } catch (e: EmailBlocklistException) {
        // Handle/notify user of exception
    }
}