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, they can choose what action to take for future messages from that sender, as well as if they should be blocked when sent to any of the user's addresses, or just a specific one.

Blocking Email Addresses

Email addresses can be blocked in batches. 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].

By default, email addresses in the batch are blocked for all addresses that the user owns. The optional emailAddressId parameter can be passed to specify that the block only applies to a specific address owned by the user.

There are two actions that can be taken when a message is received from a blocked email address. These can be specified by passing the optional action parameter with one of the enum values below.

Action	Definition
DROP	The incoming message will be dropped and not appear in the user's account.
SPAM	The incoming message will be redirected to the user's SPAM folder, if your environment is configured to do so. Otherwise, it will revert to the DROP action.

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 = [
  '[e-mail]', 
  '[e-mail]',
]
let emailAddressId: string | undefined
// Set the emailAddressId if you want to block for just a specific address
emailAddressId = emailAddress.id
let action: BlockedAddressAction | undefined
// Set the action if you want to specify an action.
action = BlockedAddressAction.Spam
try {
    const blockingResult = await emailClient.blockEmailAddresses({
        addressesToBlock,
        emailAddressId,
        action,
    })
    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]"]
let emailAddressId: String?
// Set the emailAddressId if you want to block for just a specific address
emailAddressId = emailAddress.id
let action: UnsealedBlockedAddress.BlockedAddressAction?
// Set the action if you want to specify an action.
action = .spam
do {
    let blockingResult = try await self.emailClient.blockEmailAddresses(
        addresses: addresses,
        emailAddressId: emailAddressId,
        action: action ?? .drop
    )
    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]"
)
var emailAddressId: String?
// Set the emailAddressId if you want to block for just a specific address
emailAddressId = emailAddress.id
var action: BlockedEmailAddressAction?
// Set the action if you want to specify an action.
action = BlockedEmailAddressAction.SPAM
launch {
    try {
        val blockingResult = withContext(Dispatcher.IO) {
            emailClient.blockEmailAddresses(
                addresses = addressesToBlock,
                emailAddressId = emailAddressId,
                action = action,
            )
        }
        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. There are two methods for achieving this. The first is by passing an array of the addresses, in the format in the format [e-mail], to be unblocked to the unblockEmailAddresses method. This method only works for addresses that were blocked without an emailAddressId parameter included.

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 hashedBlockedValue (returned from the getEmailAddressBlocklist endpoint below). This is the method that must be used for addresses that were blocked with the emailAddressIdparameter included and can also 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 five 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.
hashedBlockedValue	The unique hash value representing the blocked address. This can be used for unblocking in the event that the plaintext address cannot be unsealed.
action	The action to take for incoming messages from blocked senders. (See above)
emailAddressId	If included, the sender is only blocked for the email address associated with this id.

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
    }
}