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 [email protected].

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.

// Obtain the email addresses to be blocked
const addressesToBlock = [
  '[email protected]', 
  '[email protected]',
]
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
}

// Obtain the email addresses to be blocked
let addresses = ["[email protected]", "[email protected]"]
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
}

// Obtain the email addresses to be blocked
val addressesToBlock = listOf(
  "[email protected]", 
  "[email protected]"
)
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 [email protected], 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.

// Obtain the email addresses to be unblocked
const addressesToUnblock = arrayOf('[email protected]', '[email protected]')
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
}

// Obtain the email addresses to be unblocked
let addresses = ["[email protected]", "[email protected]"]
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
}

// Obtain the email addresses to be unblocked
val addressesToUnblock = listOf("[email protected]", "[email protected]")
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.

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

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

// 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.

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

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

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

PreviousSchedule Send NextEmail Address Public Information

Last updated 3 months ago