# Manage Email Address Blocklists

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 `foo-bar@domain.com.` 

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

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

```typescript
// Obtain the email addresses to be blocked
const addressesToBlock = [
  'email-address-1@domain.com', 
  'email-address-2@domain.com',
]
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
}  
```

{% endtab %}

{% tab title="Swift" %}

```swift
// Obtain the email addresses to be blocked
let addresses = ["email-address-1@domain.com", "email-address-2@domain.com"]
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
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// Obtain the email addresses to be blocked
val addressesToBlock = listOf(
  "email-address-1@domain.com", 
  "email-address-2@domain.com"
)
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
    }
}
```

{% endtab %}
{% endtabs %}

## 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 `foo-bar@domain.com`, 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.

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

```typescript
// Obtain the email addresses to be unblocked
const addressesToUnblock = arrayOf('email-address-1@domain.com', 'email-address-2@domain.com')
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
}
```

{% endtab %}

{% tab title="Swift" %}

```swift
// Obtain the email addresses to be unblocked
let addresses = ["email-address-1@domain.com", "email-address-2@domain.com"]
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
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
// Obtain the email addresses to be unblocked
val addressesToUnblock = listOf("email-address-1@domain.com", "email-address-2@domain.com")
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
    }
}
```

{% endtab %}
{% endtabs %}

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 `emailAddressId`parameter 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 `hashedValue`s instead of plaintext addresses.

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

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

{% endtab %}

{% tab title="Swift" %}

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

{% endtab %}

{% tab title="Kotlin" %}

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

{% endtab %}
{% endtabs %}

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

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

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

{% endtab %}

{% tab title="Swift" %}

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

{% endtab %}

{% tab title="Kotlin" %}

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

{% endtab %}
{% endtabs %}