# Managing lists and subscriptions in Amazon Simple Email Service
You can manage your own lists for mailing and subscriptions as well as for email suppression in Amazon SES. To help you maintain your sender reputation, SES offers account-level and configuration set-level suppression that prevents you from sending to invalid recipients and harming your sender reputation. As another measure against bounced emails and complaints, SES can automatically add unsubscribe links to all outgoing mail through subscription management.
Each of these types of lists is discussed in detail in the sections listed in this chapter's topics; however, an overview of suppression lists is presented here to understand how they differ as well as a key change with global suppression list management. It's suggested that you read this overview before working with any of the lists discussed in this chapter.
**Overview of suppression lists and suppression override mechanism**
The global suppression list removal feature is no longer customer facing and you no longer interact with it to manage suppression. The global suppression list operates and is managed in the background by SES. As a customer, you now have available to you an account-level suppression list and configuration set-level suppression overrides that offer you more customized control over how you handle email suppression for your own account.
The different types of suppression lists, their scope, and what advantages they offer is explained below.
+ **Global suppression list** – Owned and managed by SES to protect the reputation of addresses in the SES shared IP pool.
+ **Account-level suppression list** – Owned and managed by the customer to protect their account reputation - *overrides the global suppression list*.
+ **Configuration set-level suppression** – An override mechanism to provide conditional or fine-grained control of the account-level suppression list through the use of overrides specified in a configuration set.
*The global suppression list* was the only type of suppression list until account-level and configuration set-level suppression was introduced in the new Amazon SES console and API v2. The global suppression list is owned and managed by SES to protect the reputation of SES. This is needed because all SES customers are sharing the same pool of IP addresses (unless they have dedicated IPs), it’s important for SES to ensure that customers aren’t sending spam or anything that would negatively impact the reputation of those IP addresses in the SES shared IP pool. While you no longer directly interact with the global suppression list, it still operates in the background and the general tenets of how the global suppression list works can also be applied to explain the overall principles of how the other types of suppression work. See [Amazon SES global suppression list](sending-email-global-suppression-list.md).
**Note**
The global suppression list removal request form is no longer in the Amazon SES console because the account-level suppression list has superseded it for all the advantages explained in this section.
*The account-level suppression list* was introduced so that customers can create and control their own suppression list and reputation, thus, the account-level suppression list applies to your account only. The account-level suppression list interface in the new console provides an easy way to manage addresses in your account-level suppression list, including bulk actions to add or remove addresses. If an address is on the global suppression list, but not on your account level suppression list *(which means you want to send to it)*, and you do send to it, Amazon SES will still attempt delivery, but if it bounces, the bounce will affect your own reputation, but no one else will get bounces because they can’t send to that email address if they aren’t using their own account level suppression list; therefore, the account-level suppression list overrides the global suppression list for your account only. See [Using the Amazon SES account-level suppression list](sending-email-suppression-list.md).
*Configuration set-level suppression*, while not a list per se, but a mechanism that enables you to configure suppression customizations and overrides to your account-level suppression list through the use of configuration sets specifically created for different email sending scenarios. For example, if your account-level suppression list is configured for both bounce and complaint addresses to be added, but you have a particular email demographic defined in a configuration set for which you're only interested in complaint addresses being added - you would achieve this by enabling this configuration set's suppression overrides so that email addresses are added to your account-level suppression list only for complaints (not bounces and complaints like is set in your account-level suppression list) from email sent with this configuration set. With configuration set-level suppression, there are different levels of overriding your account-level suppression, including not using any suppression at all. See [Using configuration set-level suppression to override your account-level suppression list](sending-email-suppression-list-config-level.md).
**Topics**
+ [Amazon SES global suppression list](sending-email-global-suppression-list.md)
+ [Using the Amazon SES account-level suppression list](sending-email-suppression-list.md)
+ [Using configuration set-level suppression to override your account-level suppression list](sending-email-suppression-list-config-level.md)
+ [Using list management](sending-email-list-management.md)
+ [Using subscription management](sending-email-subscription-management.md)
# Amazon SES global suppression list
Amazon SES maintains an internal *global suppression list* which operates and is managed in the background by SES. When any SES customer sends an email that results in a hard bounce, SES adds the email address that produced the bounce to a global suppression list. The global suppression list is *global* in the sense that it applies to all SES customers. In other words, if a different customer attempts to send an email to an address that's on the global suppression list, SES accepts the message, but doesn't send it, because the email address is suppressed.
The global suppression list email address removal request feature *is no longer customer facing and you no longer interact with it* to manage suppression. To replace this functionality, Amazon SES now offers a new way for you to manage your suppression by making available an **account-level suppression list** and **configuration set-level suppression overrides** that offer you more customized control over how you handle email suppression for your own account. For more information, see [Using the Amazon SES account-level suppression list](sending-email-suppression-list.md) and [Using configuration set-level suppression to override your account-level suppression list](sending-email-suppression-list-config-level.md).
**Important**
The global suppression list email address removal request form is no longer in the Amazon SES console because the account-level suppression list has superseded it. To learn how to use the account-level suppression list, see [Using the Amazon SES account-level suppression list](sending-email-suppression-list.md).
## Global suppression list considerations
Key factors regarding the global suppression list:
+ The global suppression list operates and is managed in the background by SES - you cannot interact with it directly; however, you can override it by using your own [account-level suppression list](sending-email-suppression-list.md).
+ The global suppression list is enabled by default for all SES accounts. You can't disable it.
+ Because SES applies the global suppression list to all customers, you can't query the global suppression list or add addresses to it manually.
+ When an email address produces a hard bounce, SES adds the address to the global suppression list for a short period of time. After that period of time elapses, SES removes the address from the list. If the address produces another hard bounce, SES adds it back to the global suppression list for a longer period of time, and removes it at the end of that period. The amount of time that an address remains on the global suppression list increases each time the address produces a hard bounce. An address can remain on the global suppression list for up to 14 days.
+ If you attempt to send a message to an address that's on the global suppression list, SES accepts the message, but doesn't send it. SES generates a bounce notification with a `bounceType` value of `Permanent`, and a `bounceSubType` value of `Suppressed`. Receiving this type of bounce notification is the only way to know if an address is on the global suppression list. You can't query the global suppression list.
+ SES counts the messages that you send to addresses on the global suppression list toward the bounce rate for your account and toward your daily sending quota.
+ As with any email address that produces a hard bounce, you should remove addresses that cause a suppression list bounce from your mailing list unless you're certain that the address is valid.
+ Suppression list bounces count towards your account's bounce rate. If your bounce rate gets too high, your account might be placed under review or your account's ability to send email could be paused.
**Note**
It's important to understand how the SES suppression lists are interrelated and their hierarchy, see [Overview of suppression lists and suppression override mechanism](lists-and-subscriptions.md#3-suppression-overview).
# Using the Amazon SES account-level suppression list
The Amazon SES account-level suppression list was introduced so that customers can create and control their own suppression list and manage their reputation, thus, your account-level suppression list applies to your account only. The account-level suppression list interface in the SES console provides an easy way to manage addresses in your account-level suppression list, including bulk actions to add or remove addresses.
Your SES *account-level suppression list* applies to your AWS account in the current AWS Region. You can add or remove, individually or in bulk, addresses from your account-level suppression list by using the SES API v2 or console.
**Note**
To bulk add or remove addresses, you must have production access. To learn more about the sandbox, see [Request production access (Moving out of the Amazon SES sandbox)](request-production-access.md).
**Important**
SES account suppression lists are case-sensitive. When an email address is added to the suppression list, *User@Example.com*, it is stored exactly as received, preserving the original case. While email sending functionality treats addresses with different cases as identical, for example, *User@Example.com* is the same as *user@example.com*, API calls for suppression list management require an exact case match. Thus, when using APIs related to suppression list management, ensure you use the exact case of the email address as it appears in the suppression list.
## Amazon SES Account-level suppression list considerations
You should consider the following factors when you use your account-level suppression list:
+ If you started using Amazon SES after November 25, 2019, your account uses the account-level suppression list by default for both bounces and complaints. If you started using SES before this date, then you have to enable this feature by using the `PutAccountSuppressionAttributes` operation in the SES API.
+ If you attempt to send a message to an address that's on your account-level suppression list that has a suppression reason that matches the same suppression reason chosen for your account-level suppression *settings*, SES accepts the message, but doesn't send it—however, if they don't match, then SES *will* send it. To help clarify this, the following examples are provided:
+ You've set your account-level suppression settings with the suppression reason of *Bounces only*, SES will not attempt delivery for addresses in your account-level suppression list with the suppression reason as *Bounce*. However, SES *will* attempt delivery for addresses in your account-level suppression list with the suppression reason of *Complaint* (because in this case, they do not match).
+ You've set your account-level suppression settings with the suppression reason of *Bounces and Complaints*, SES will not attempt delivery for addresses in your account-level suppression list with a suppression reason of either *Bounce* or *Complaint*.
+ SES doesn't count the messages that you send to addresses on your account-level suppression list towards the *Reputation.BounceRate* or *Reputation.ComplaintRate* metrics in the AWS/SES namespace for your account. Such messages are counted under *Bounce* or *Complaint* metrics in the AWS/SES namespace.
+ If an address is on the global suppression list, but not on your account level suppression list *(which means you want to send to it)*, and you do send to it, SES will still attempt delivery; however, if it bounces, it still counts toward the bounce rate for your account and toward your daily sending quota.
+ SES counts the messages that you send to addresses on your account-level suppression list toward your daily sending quota.
+ Email addresses on your account-level suppression list remain there until you remove them.
+ If your account's ability to send email is paused, SES automatically deletes the addresses in your account-level suppression list after 90 days. If your account's ability to send email is restored before this 90-day period ends, then the addresses in the list aren't deleted.
+ Gmail doesn't provide complaint data to SES. If a recipient uses the **Spam** button in the Gmail web client to report a message that they receive from you as spam, they aren't added to your account-level suppression list.
+ You can enable your account-level suppression list if your account is in the SES sandbox. However, you can't use the [PutSuppressedDestination](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_PutSuppressedDestination) or [CreateImportJob](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) operation until your account is removed from the sandbox. To learn more about the sandbox, see [Request production access (Moving out of the Amazon SES sandbox)](request-production-access.md).
+ Only hard bounces are added to your account-level suppression list. For information about the differences between soft and hard bounces, see [After Amazon SES sends an email](send-email-concepts-process.md#send-email-concepts-process-after-send).
+ When you use your account-level suppression list, SES adds addresses that result in hard bounces to the global suppression list as well.
**Note**
The procedures in the following sections assume that you've already installed the AWS CLI. For more information about installing and configuring the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/).
## Enabling the Amazon SES account-level suppression list
You can use the [PutAccountSuppressionAttributes](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_PutAccountSuppressionAttributes.html) operation in the Amazon SES API v2 to enable and set up your account-level suppression list. You can quickly and easily configure this setting by using the AWS CLI. For more information about installing and configuring the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/).
**To configure your account-level suppression list using the AWS CLI**
+ At the command line, enter the following command:
------
#### [ Linux, macOS, or Unix ]
```
aws sesv2 put-account-suppression-attributes \
--suppressed-reasons BOUNCE COMPLAINT
```
------
#### [ Windows ]
```
aws sesv2 put-account-suppression-attributes `
--suppressed-reasons BOUNCE COMPLAINT
```
------
To enable your account-level suppression list, you have to specify at least one reason for the `suppressed-reasons` parameter. You can specify either `BOUNCE` or `COMPLAINT`, or you can specify both, as shown in the preceding example.
**To configure your account-level suppression list using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. In the **Account-level settings** pane, choose **Edit**.
1. In **Suppression list**, check the **Enabled** box.
1. In **Suppression reasons**, select one of the reasons for which recipient email addresses should be automatically added to your account-level suppression list.
1. Choose **Save changes**.
## Enabling the Amazon SES account-level suppression list for a configuration set
You can also configure your Amazon SES account-level suppression so that it only applies to specific [configuration sets](using-configuration-sets.md). When you do, addresses are only added to the suppression list if you specified the configuration set when you sent the email that caused the bounce or complaint event.
**To configure your account-level suppression list for a configuration set using the AWS CLI**
+ At the command line, enter the following command:
------
#### [ Linux, macOS, or Unix ]
```
aws sesv2 put-configuration-set-suppression-options \
--configuration-set-name configSet \
--suppressed-reasons BOUNCE COMPLAINT
```
------
#### [ Windows ]
```
aws sesv2 put-configuration-set-suppression-options `
--configuration-set-name configSet `
--suppressed-reasons BOUNCE COMPLAINT
```
------
In the preceding example, replace *configSet* with the name of the configuration set that should use your account-level suppression list.
**To configure your account-level suppression list for a configuration set using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Configuration sets**.
1. In **Configuration sets**, choose the name of the configuration set you want to configure with customized suppression.
1. In the **Suppression list options** pane, choose **Edit**.
1. The **Suppression list options** section provides a decision set to define customized suppression starting with the option to use this configuration set to override your account-level suppression. The [configuration set-level suppression logic map](sending-email-suppression-list-config-level.md) will help you understand the effects of the override combinations. These multitiered selections of overrides can be combined to implement three different levels of suppression:
1. **Use account-level suppression:** Do not override your account-level suppression and do not implement any configuration set-level suppression - basically, any email sent using this configuration set will just use your account-level suppression. To do this:
1. In **Suppression list settings**, uncheck the **Override account level settings** box.
1. **Do not use any suppression:** Override your account-level suppression without enabling any configuration set-level suppression - this means any email sent using this configuration set will not use any of your account-level suppression; in other words, all suppression is cancelled. To do this:
1. In **Suppression list settings**, check the **Override account level settings** box.
1. In **Suppression list**, uncheck the **Enabled** box.
1. **Use configuration set-level suppression:** Override your account-level suppression with custom suppression list settings defined in this configuration set - this means any email sent using this configuration set will only use its own suppression settings and ignore any account-level suppression settings. To do this:
1. In **Suppression list settings**, check the **Override account level settings** box.
1. In **Suppression list**, check **Enabled**.
1. In **Specify the reason(s)...**, select one of the suppression reasons for this configuration set to use.
1. Choose **Save changes**.
## Adding individual email addresses to the Amazon SES account-level suppression list
You can add individual addresses to your Amazon SES account-level suppression list by using the [PutSuppressedDestination](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_PutSuppressedDestination.html) operation in the SES API v2. There's no limit to the number of addresses that you can add to your account-level suppression list.
**To add individual addresses to your account-level suppression list using the AWS CLI**
+ At the command line, enter the following command:
------
#### [ Linux, macOS, or Unix ]
```
aws sesv2 put-suppressed-destination \
--email-address recipient@example.com \
--reason BOUNCE
```
------
#### [ Windows ]
```
aws sesv2 put-suppressed-destination `
--email-address recipient@example.com `
--reason BOUNCE
```
------
In the preceding example, replace *recipient@example.com* with the email address that you want to add to your account-level suppression list, and *BOUNCE* with the reason that you're adding the address to the suppression list (acceptable values are `BOUNCE` and `COMPLAINT`).
**To add individual addresses to your account-level suppression list using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. In the **Suppression list** pane, choose **Add email address**.
1. Type an email address in the **Email address** field followed by selecting a reason in **Suppression reason** - if you need to enter more addresses, choose **Enter another address** and repeat for each additional one.
1. When done entering addresses, review your entries for accuracy. If you decide any of your entries shouldn't be part of this submission, choose its **Remove** button.
1. Choose **Save changes** to add the entered email addresses to your account-level suppression list.
## Adding email addresses in bulk to your Amazon SES account-level suppression list
You can add addresses in bulk by first uploading your contact list into an Amazon S3 object followed by using the [CreateImportJob](#CIJ-add-bulk-API) operation in the Amazon SES API v2.
**Note**
There's no limit to the number of addresses that you can add to your account-level suppression list, but there is a bulk add limit of 100,000 addresses in an Amazon S3 object per API call.
You cannot run more than 20 concurrent import jobs.
If your data source is an S3 bucket, it must exist in the same region as you're importing into.
To add email addresses in bulk to your account-level suppression list, complete the following steps.
+ Upload your address list into an Amazon S3 object in either CSV or JSON format.
CSV format example for adding addresses:
`recipient1@example.com,BOUNCE`
`recipient2@example.com,COMPLAINT`
Only newline-delimited JSON files are supported. In this format, each line is a complete JSON object that contains an individual address definition.
JSON format example for adding addresses:
`{"emailAddress":"recipient1@example.com","reason":"BOUNCE"}`
`{"emailAddress":"recipient2@example.com","reason":"COMPLAINT"}`
In the preceding examples, replace *recipient1@example.com* and *recipient2@example.com* with the email addresses that you want to add to your account-level suppression list. The acceptable reasons that you're adding the addresses to the suppression list are `BOUNCE` and `COMPLAINT`.
+ Give SES permission to use your AWS KMS key.
If the Amazon S3 object is encrypted with an AWS KMS key, you need to give Amazon SES permission to use the AWS KMS key. SES can only attain permission from a customer managed key, not a default KMS key. You need to give SES permission to use the customer managed key by adding a statement to the key's policy.
Paste the following policy statement into the key policy to permit SES to use your customer managed key.
```
{
"Sid": "AllowSESToDecrypt",
"Effect": "Allow",
"Principal": {
"Service":"ses.amazonaws.com"
},
"Action": [
"kms:Decrypt",
],
"Resource": "*"
}
```
+ Use the [CreateImportJob](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) operation in the SES API v2.
**Note**
The following example assumes that you've already installed the AWS CLI. For more information about installing and configuring the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/).
At the command line, enter the following command. Replace *s3bucket* with the name of an Amazon S3 bucket and *s3object* with the name of an Amazon S3 object.
```
aws sesv2 create-import-job --import-destination SuppressionListDestination={SuppressionListImportAction=PUT} --import-data-source S3Url=s3://s3bucket/s3object,DataFormat=CSV
```
**To add email addresses in bulk to your account-level suppression list using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. In the **Suppression list** table, expand the **Bulk actions** button and select **Add email addresses in bulk**.
1. In **Bulk action specifications**, select either (a)**Choose file from S3 bucket** or (b)**Import from file** - procedures are given for each import method:
1. **Choose file from S3 bucket** - *if your source file is already stored in an Amazon S3 bucket*:
1. If you know the URI of the Amazon S3 bucket you want to use, enter it in the **Amazon S3 URI** field; otherwise, choose **Browse S3**:
1. In **Buckets**, select the name of the S3 bucket.
1. In **Objects**, select the name of the file then select **Choose** - you'll be returned to **Bulk action specifications**.
1. (Optional) If you want to be taken to the Amazon S3 console to view details about your S3 object choose **View**.
1. In **File format**, select the format of the file you've chosen to import from you Amazon S3 bucket.
1. Choose **Add email addresses** to kick off the import of addresses from your file - a table under the **Bulk actions** tab is displayed.
1. **Import from file** - *if you have a local source file to upload to a new or existing Amazon S3 bucket*:
1. In **Import source file**, select **Choose file**.
1. Select the JSON or CSV file in the file browser and choose **Open** - you'll see the name, size, and date of your file displayed under the **Choose file** button.
1. Expand **Amazon S3 bucket** and select the S3 bucket.
1. To upload your file to a new bucket, choose **Create S3 bucket**, enter a name in the **Bucket name** field, and choose **Create bucket**.
1. Choose **Add email addresses** to kick off the import of addresses from your file - a table under the **Bulk actions** tab is displayed.
1. Regardless of the import method you used, your job ID will be listed in **Bulk actions** along with import type, status, and date - to view job details, select the job ID.
1. Select the **Suppression list** tab and all the successfully imported email addresses are displayed with their suppression reason and date added - the following options are available:
1. Select an email address, or select its corresponding checkbox and choose **View report** to view its details. (If it's an address that was automatically added to your suppression list because of a bounce or complaint, information will be displayed about the feedback event that caused it to be added, including details about the email message that produced the triggering event.)
1. Select the corresponding checkbox of one or more email addresses you want to remove from your account suppression list and choose **Remove**.
## Viewing a list of addresses that are on your Amazon SES account-level suppression list
You can view a list of all of the email addresses that are on your account-level suppression list for your account by using the [ListSuppressedDestinations](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListSuppressedDestinations.html) operation in the SES API v2.
**To view a list of all of the email addresses that are on your account-level suppression list**
+ At the command line, enter the following command:
```
aws sesv2 list-suppressed-destinations
```
The preceding command returns all of the email addresses that are in your account-level suppression list for your account. The output resembles the following example:
```
{
"SuppressedDestinationSummaries": [
{
"EmailAddress": "recipient2@example.com",
"Reason": "COMPLAINT",
"LastUpdateTime": "2020-04-10T21:03:05Z"
},
{
"EmailAddress": "recipient0@example.com",
"Reason": "COMPLAINT",
"LastUpdateTime": "2020-04-10T21:04:26Z"
},
{
"EmailAddress": "recipient1@example.com",
"Reason": "BOUNCE",
"LastUpdateTime": "2020-04-10T22:07:59Z"
}
]
}
```
+ **Note** – If your output includes a "NextToken" field with a string value, this indicates there are additional email addresses on the suppression list for your account. To view additional suppressed addresses, issue another request to `ListSuppressedDestinations`, and pass the returned string value in the `--next-token` parameter like so:
```
aws sesv2 list-suppressed-destinations --next-token string
```
In the preceding command, replace *string* with the returned NextToken value.
For more information, see [How to list over 1000 email addresses from account-level suppression list](https://aws.amazon.com/blogs/messaging-and-targeting/how-to-list-over-1000-email-addresses-from-account-level-suppression-list/).
You can use the `StartDate` option to only show email addresses that were added to the list *after* a certain date.
**To view a list of addresses that were added to your account-level suppression list after a specific date**
+ At the command line, enter the following command:
```
aws sesv2 list-suppressed-destinations --start-date 1604394130
```
In the preceding command, replace *1604394130* with the Unix timestamp of the start date.
You can also use the `EndDate` option to only show email addresses that were added to the list *before* a certain date.
**To view a list of addresses that were added to your account-level suppression list before a specific date**
+ At the command line, enter the following command:
```
aws sesv2 list-suppressed-destinations --end-date 1611126000
```
In the preceding command, replace *1611126000* with the Unix timestamp of the end date.
On the Linux, macOS, or Unix command line, you can also use the built-in `grep` utility to search for specific addresses or domains.
**To search your account-level suppression list for a specific address**
+ At the command line, enter the following command:
```
aws sesv2 list-suppressed-destinations | grep -A2 'example.com'
```
In the preceding command, replace *example.com* with the string of text (such as the address or domain) that you want to search for.
**To view a list of all of the email addresses that are on your account-level suppression list using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. In the **Suppression list** pane, all the email addresses on your account-level suppression list are displayed with their suppression reason and date added - the following options are available:
1. Select an email address, or select its corresponding checkbox and choose **View report** to view its details. (If it's an address that was automatically added to your suppression list because of a bounce or complaint, information will be displayed about the feedback event that caused it to be added, including details about the email message that produced the triggering event.)
1. You can customize the suppression list table by choosing the gear icon - a modal will be presented where you can customize page size, line wrap, and columns to view - after making your selections, choose **Confirm**. The suppression list table will reflect your viewing choices.
## Removing individual email addresses from your Amazon SES account-level suppression list
If an address is on the suppression list for your account, but you know that the address shouldn't be on the list, you can remove it by using [DeleteSuppressedDestination](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_DeleteSuppressedDestination.html) operation in the SES API v2.
**To remove individual addresses from your account-level suppression list using the AWS CLI**
+ At the command line, enter the following command:
------
#### [ Linux, macOS, or Unix ]
```
aws sesv2 delete-suppressed-destination \
--email-address recipient@example.com
```
------
#### [ Windows ]
```
aws sesv2 delete-suppressed-destination `
--email-address recipient@example.com
```
------
In the preceding example, replace *recipient@example.com* with the email address that you want to remove from your account-level suppression list.
**To remove individual addresses from your account-level suppression list using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. Remove individual email addresses either by *(a)* table selection or *(b)* typed entry:
1. *Select from table*: In the **Suppression list** table, select the corresponding checkbox of one or more email addresses and choose **Remove**.
1. *Type in field*:
1. In the **Suppression list** table, choose **Remove email address**.
1. Type an email address in the **Email address** field - if you need to enter more addresses, choose **Enter another address** and repeat for each additional one.
1. When done entering addresses, review your entries for accuracy. If you decide any of your entries shouldn't be part of this submission, choose its **Remove** button.
1. Choose **Save changes** to remove the entered email addresses from your account-level suppression list.
## Removing email addresses in bulk from your Amazon SES account-level suppression list
You can remove addresses in bulk by first uploading your contact list into an Amazon S3 object followed by using the [CreateImportJob](#CIJ-remove-bulk-API) operation in the SES API v2.
**Note**
There's no limit to the number of addresses that you can remove from the account-level suppression list, but there is a bulk delete limit of 10,000 addresses in an Amazon S3 object per API call.
If your data source is an S3 bucket, it must exist in the same region as you're importing into.
To remove email addresses in bulk from your account-level suppression list, complete the following steps.
+ Upload your address list into an Amazon S3 object in either CSV or JSON format.
CSV format example for removing addresses:
`recipient3@example.com`
Only newline-delimited JSON files are supported. In this format, each line is a complete JSON object that contains an individual address definition.
JSON format example for adding addresses:
`{"emailAddress":"recipient3@example.com"}`
In the preceding examples, replace *recipient3@example.com* with the email addresses that you want to remove from your account-level suppression list.
+ Give SES permission to read the Amazon S3 object.
When applied to an Amazon S3 bucket, the following policy gives SES permission to read that bucket. For more information about attaching policies to Amazon S3 buckets, see [Using Bucket Policies and User Policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-iam-policies.html) in the *Amazon Simple Storage Service User Guide*.
+ Give SES permission to use your AWS KMS key.
If the Amazon S3 object is encrypted with an AWS KMS key, you need to give Amazon SES permission to use the AWS KMS key. SES can only attain permission from a customer managed key, not a default KMS key. You need to give SES permission to use the customer managed key by adding a statement to the key's policy.
Paste the following policy statement into the key policy to permit SES to use your customer managed key.
```
{
"Sid": "AllowSESToDecrypt",
"Effect": "Allow",
"Principal": {
"Service":"ses.amazonaws.com"
},
"Action": [
"kms:Decrypt",
],
"Resource": "*"
}
```
+ Use the [CreateImportJob](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) operation in the SES API v2.
**Note**
The following example assumes that you've already installed the AWS CLI. For more information about installing and configuring the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/).
At the command line, enter the following command. Replace *s3bucket* with the name of the Amazon S3 bucket and *s3object* with the name of the Amazon S3 object.
```
aws sesv2 create-import-job --import-destination SuppressionListDestination={SuppressionListImportAction=DELETE} --import-data-source S3Url="s3://s3bucket/s3object",DataFormat=CSV
```
**To remove email addresses in bulk from your account-level suppression list using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. In the **Suppression list** table, expand the **Bulk actions** button and select **Remove email addresses in bulk**.
1. In **Bulk action specifications**, select either (a) **Choose file from S3 bucket** or (b) **Import from file** - procedures are given for each import method:
1. **Choose file from S3 bucket** - *if your source file is already stored in an Amazon S3 bucket*:
1. If you know the URI of the Amazon S3 bucket you want to use, enter it in the **Amazon S3 URI** field; otherwise, choose **Browse S3**:
1. In **Buckets**, select the name of the S3 bucket.
1. In **Objects**, select the name of the file then select **Choose** - you'll be returned to **Bulk action specifications**.
1. (Optional) If you want to be taken to the Amazon S3 console to view details about your S3 object choose **View**.
1. In **File format**, select the format of the file you've chosen to import from your Amazon S3 bucket.
1. Choose **Remove email addresses** to kick off the import of addresses from your file - a table under the **Bulk actions** tab is displayed.
1. **Import from file** - *if you have a local source file to upload to a new or existing Amazon S3 bucket*:
1. In **Import source file**, select **Choose file**.
1. Select the JSON or CSV file in the file browser and choose **Open** - you'll see the name, size, and date of your file displayed under the **Choose file** button.
1. Expand **Amazon S3 bucket** and select the S3 bucket.
1. To upload your file to a new bucket, choose **Create S3 bucket**, enter a name in the **Bucket name** field, and choose **Create bucket**.
1. Choose **Remove email addresses** to kick off the import of addresses from your file - a table under the **Bulk actions** tab is displayed.
1. Regardless of the import method you used, your job ID will be listed in **Bulk actions** along with import type, status, and date - to view job details, select the job ID.
1. Select the **Suppression list** tab and all the successfully imported email addresses that were removed from your suppression list will no longer be displayed.
## Viewing a list of import jobs for the account
You can view a list of all of the email addresses that are on your account-level suppression list for your account by using the [ListImportJobs](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListImportJobs.html) operation in the Amazon SES API v2.
**To view a list of all of the import jobs for the account**
+ At the command line, enter the following command:
```
aws sesv2 list-import-jobs
```
The preceding command returns all of the import jobs for the account. The output resembles the following example:
```
{
"ImportJobs": [
{
"CreatedTimestamp": 2020-07-31T06:06:55Z",
"ImportDestination": {
"SuppressionListDestination": {
"SuppressionListImportAction": "PUT"
}
},
"JobStatus": "COMPLETED",
"JobId": "755380d7-fbdb-4ed2-a9a3-06866220f5b5"
},
{
"CreatedTimestamp": "2020-07-30T18:45:32Z",
"ImportDestination": {
"SuppressionListDestination": {
"SuppressionListImportAction": "DELETE"
}
},
"JobStatus": "COMPLETED",
"JobId": "076683bd-a7ee-4a40-9754-4ad1161ba8b6"
},
{
"CreatedTimestamp": "2020-08-05T16:45:18Z",
"ImportDestination": {
"SuppressionListDestination": {
"SuppressionListImportAction": "PUT"
}
},
"JobStatus": "COMPLETED",
"JobId": "6e261869-bd30-4b33-b1f2-9e035a83a395"
}
]
}
```
**To view a list of all of the import jobs for the account using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. In the **Suppression list** pane, select the **Bulk actions** tab.
1. All the import jobs will be listed in the **Bulk actions** table along with import type, status, and date.
1. To view job details, select the job ID and the following panes are displayed:
1. **Bulk action status**: shows the jobs overall status, the time and date it completed, how many records where imported, and the count of any records that failed to import successfully.
1. **Bulk action details**: shows the job ID, whether it was used to add or remove addresses, whether the file format was JSON or CSV, the URI of the Amazon S3 bucket where the bulk file was stored, and the time and date the bulk action was created.
## Getting information about an import job for the account
You can get information about an import job for the account by using the [GetImportJob](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_GetImportJob.html) operation in the Amazon SES API v2.
**To get information about an import job for the account**
+ At the command line, enter the following command:
```
aws sesv2 get-import-job --job-id JobId
```
The preceding command returns information about an import job for the account. The output resembles the following example:
```
{
"ImportDataSource": {
"S3Url": "s3://bucket/object",
"DataFormat": "CSV"
},
"ProcessedRecordsCount": 2,
"FailureInfo": {
"FailedRecordsS3Url": "s3presignedurl"
},
"JobStatus": "COMPLETED",
"JobId": "jobid",
"CreatedTimestamp": "2020-08-12T17:05:15Z",
"FailedRecordsCount": 1,
"ImportDestination": {
"SuppressionListDestination": {
"SuppressionListImportAction": "PUT"
}
},
"CompletedTimestamp": "2020-08-12T17:06:42Z"
}
```
**To get information about an import job for the account using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. In the **Suppression list** pane, select the **Bulk actions** tab.
1. All the import jobs will be listed in the **Bulk actions** table along with import type, status, and date.
1. To view job details, select the job ID and the following panes are displayed:
1. **Bulk action status**: shows the jobs overall status, the time and date it completed, how many records where imported, and the count of any records that failed to import successfully.
1. **Bulk action details**: shows the job ID, whether it was used to add or remove addresses, whether the file format was JSON or CSV, the URI of the Amazon S3 bucket where the bulk file was stored, and the time and date the bulk action was created.
## Disabling the Amazon SES account-level suppression list
You can use the [PutAccountSuppressionAttributes](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_PutAccountSuppressionAttributes.html) operation in the SES API v2 to effectively disable your account-level suppression list by removing the values from the `suppressed-reasons` attribute.
**To disable your account-level suppression list using the AWS CLI**
+ At the command line, enter the following command:
```
aws sesv2 put-account-suppression-attributes --suppressed-reasons
```
**To disable your account-level suppression list using the SES console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Suppression list**.
1. In the **Account-level settings** pane, choose **Edit**.
1. In **Suppression list**, uncheck the **Enabled** box.
1. Choose **Save changes**.
# Using configuration set-level suppression to override your account-level suppression list
While the account-level suppression list is set for your entire account, you can customize it separately for different configuration sets by overriding it with configuration set-level suppression. This finer granularity allows you to use customized suppression settings for different email sending groups that you've assigned to their own configuration sets. For example, let's say your account-level suppression list is configured for both bounce and complaint addresses to be added, but you have a particular email demographic defined in a configuration set for which you're only interested in complaint addresses being added - you would achieve this by enabling this configuration set's suppression overrides so that email addresses are added to your account-level suppression list just for complaints (not bounces and complaints like is set in your account-level suppression list) from email sent with this configuration set.
With configuration set-level suppression, there are different levels of overriding your account-level suppression, including not using any suppression at all. To help understand these various levels of suppression that can be set in the following console procedures, the following relationship map models the decision set of choices you can make for the enabling or disabling of various levels of overrides, that depending on their combination, can be used to implement three different levels of suppression:
+ **No overrides (default)** – the configuration set uses your account-level suppression list settings.
+ **Override account level settings** – this will negate any account-level suppression list settings; email sent with this configuration set will not use any suppression settings at all.
+ **Override account level settings with configuration set-level suppression enabled** – email sent with this configuration set will only use the suppression conditions you enabled for it (bounces, complaints, or bounces and complaints) - regardless of what your account-level suppression list settings are, it will override them.
**Note**
For any suppression condition *not* specified at the configuration set-level, suppression behavior will fall back to the global suppression list since account-level settings have been overridden.
![\[Flowchart showing configuration set-level suppression logic with override options.\]](http://docs.aws.amazon.com/ses/latest/dg/images/config_set_suppression_logic.png)
Keep in mind that configuration set-level suppression is not an actual suppression *list*, rather, it's simply a mechanism to override your account-level suppression list with custom suppression settings defined in a configuration set - this means any email sent using the configuration set will only use its own suppression settings and ignore any account-level suppression settings. In other words, configuration set-level suppression is interacting with your account-level suppression list by simply changing (overriding) the suppression reasons that determine what email addresses get added to your account-level suppression list.
## Enabling configuration set-level suppression
**To enable configuration set-level suppression using the Amazon SES new console:**
1. Sign in to the AWS Management Console and open the Amazon SES console at [https://console.aws.amazon.com/ses/](https://console.aws.amazon.com/ses/).
1. In the navigation pane, under **Configuration**, choose **Configuration sets**.
1. In **Configuration sets**, choose the name of the configuration set you want to configure with customized suppression.
1. In the **Suppression list options** pane, choose **Edit**.
1. The **Suppression list options** section provides a decision set to define customized suppression starting with the option to use this configuration set to override your account-level suppression. The [configuration set-level suppression logic map](#sending-email-suppression-list-config-level) will help you understand the effects of the override combinations. These multitiered selections of overrides can be combined to implement three different levels of suppression:
1. **Use account-level suppression:** Do not override your account-level suppression and do not implement any configuration set-level suppression - basically, any email sent using this configuration set will just use your account-level suppression. To do this:
1. In **Suppression list settings**, uncheck the **Override account level settings** box.
1. **Do not use any suppression:** Override your account-level suppression without enabling any configuration set-level suppression - this means any email sent using this configuration set will not use any of your account-level suppression; in other words, all suppression is cancelled. To do this:
1. In **Suppression list settings**, check the **Override account level settings** box.
1. In **Suppression list**, uncheck the **Enabled** box.
1. **Use configuration set-level suppression:** Override your account-level suppression list with custom suppression settings defined in this configuration set - this means any email sent using this configuration set will only use its own suppression settings and ignore any account-level suppression settings. To do this:
1. In **Suppression list settings**, check the **Override account level settings** box.
1. In **Suppression list**, check **Enabled**.
1. In **Specify the reason(s)...**, select one of the suppression reasons for this configuration set to use.
1. Choose **Save changes**.
# Using list management
Amazon SES offers list management capabilities, which means customers can manage their own mailing lists, known as contact lists. A *contact list* is a list that allows you to store all of your contacts that have subscribed to a particular topic or topics. A *contact* is an end-user who is receiving your emails. A *topic* is an interest group, theme, or label within a list. Lists can have multiple topics.
By using the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html) operation in the Amazon SES API v2, you can retrieve a list of all your contacts who have subscribed to a particular topic, to whom you can send emails using the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) operation.
For information about subscription management, see [Using subscription management](sending-email-subscription-management.md).
## List management overview
You should consider the following factors when you use list management:
+ You can specify list topics while creating the list.
+ Only one contact list is allowed per AWS account.
+ A list can have a maximum of 20 topics.
+ You can update an existing contact list, including adding new topics to the list, adding or deleting contacts from a list, and updating contact preferences for a list or topic.
+ You can update topic metadata, such as the topic display name or description.
+ You can get a list of contacts in a contact list, contacts subscribed to a topic, contacts unsubscribed from a topic, and contacts unsubscribed from all topics in the list.
+ You can import your existing contact lists to SES using the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) API.
+ SES will issue a bounce event for a message that is sent to an unsubscribed contact on your contact list. For more information, see [Using subscription management](sending-email-subscription-management.md).
+ Each contact can have associated attributes which you can use to store information about that contact.
## Configuring list management
You can use the following operations to configure list management capabilities. For the full list of contact list and contact operations, see the [Amazon SES API v2 Reference](https://docs.aws.amazon.com/ses/latest/APIReference-V2/Welcome.html).
### Create a contact list
You can use the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html) operation in the SES API v2 to create a contact list. You can quickly and easily configure this setting by using the AWS CLI. For more information about installing and configuring the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/).
**To create a contact list by using the AWS CLI**
+ At the command line, enter the following command:
```
aws sesv2 create-contact-list --cli-input-json file://CONTACT-LIST-JSON
```
In the preceding command, replace *CONTACT-LIST-JSON* with the path to your JSON file for your [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html) request.
An example `CreateContactList` input JSON file for the request is as follows:
```
{
"ContactListName": "ExampleContactListName",
"Description": "Creating a contact list example",
"Topics": [
{
"TopicName": "Sports",
"DisplayName": "Sports Newsletter",
"Description": "Sign up for our free newsletter to receive updates on all sports.",
"DefaultSubscriptionStatus": "OPT_OUT"
},
{
"TopicName": "Cycling",
"DisplayName": "Cycling newsletter",
"Description": "Never miss a cycling update by subscribing to our newsletter.",
"DefaultSubscriptionStatus": "OPT_IN"
},
{
"TopicName": "NewProducts",
"DisplayName": "New products",
"Description": "Hear about new products by subscribing to this mailing list.",
"DefaultSubscriptionStatus": "OPT_IN"
},
{
"TopicName": "DailyUpdates",
"DisplayName": "Daily updates",
"Description": "Start your day with sport updates, Monday through Friday.",
"DefaultSubscriptionStatus": "OPT_OUT"
}
]
}
```
### Create a contact
You can use the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html) operation in the SES API v2 to create a contact. You can quickly and easily configure this setting by using the AWS CLI. For more information about installing and configuring the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/).
**To create a contact by using the AWS CLI**
+ At the command line, enter the following command:
```
aws sesv2 create-contact --cli-input-json file://CONTACT-JSON
```
In the preceding command, replace *CONTACT-JSON* with the path to your JSON file for your [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html) request.
An example `CreateContact` input JSON file for the request is as follows:
```
{
"ContactListName": "ExampleContactListName",
"EmailAddress": "example@amazon.com",
"UnsubscribeAll": false,
"TopicPreferences": [
{
"TopicName": "Sports",
"SubscriptionStatus": "OPT_IN"
}
],
"AttributesData": "{\"Name\": \"John\", \"Location\": \"Seattle\"}"
}
```
In the example above, an `UnsubscribeAll` value of `false` shows that the contact has not unsubscribed from all topics, where a value of `true` would mean the contact has unsubscribed from all topics.
`TopicPreferences` includes information about the contact’s subscription status to topics. In the preceding example, the contact has opted in to the "*Sports*" topic and will receive all emails to the "*Sports*" topic.
The `AttributesData` is a JSON field where you can put any metadata about our contact. It must be a valid JSON object.
### Bulk importing contacts to your contact list
You can manually add addresses in bulk by first uploading your contacts into an Amazon S3 object followed by using the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) operation in the SES API v2 or by using the SES console. For more information see [Adding email addresses in bulk to your account-level suppression list](sending-email-suppression-list.md#sending-email-suppression-list-manual-add-bulk).
You should create a contact list before importing your contacts.
**Note**
You can add up to 1 million contacts to a contact list per ImportJob.
To add contacts in bulk to your contact list, complete the following steps.
+ Upload your contacts into an Amazon S3 object in either CSV or JSON format.
**CSV format**
The first line of the file that is uploaded to Amazon S3 should be a header line.
The `topicPreferences` object needs to be flattened for the CSV format. Every topic in the `topicPreferences` will have a separate header field.
CSV format example for adding contacts in bulk to a contact list:
```
emailAddress,unsubscribeAll,attributesData,topicPreferences.Sports,topicPreferences.Cycling
example1@amazon.com,false,{"Name": "John"},OPT_IN,OPT_OUT
example2@amazon.com,true,,OPT_OUT,OPT_OUT
```
**JSON format**
Only newline-delimited JSON files are supported. In this format, each line is a complete JSON object that contains one contact's information.
JSON format example for adding contacts in bulk to a contact list:
```
{
"emailAddress": "example1@amazon.com",
"unsubscribeAll": false,
"attributesData": "{\"Name\":\"John\"}",
"topicPreferences": [
{
"topicName": "Sports",
"subscriptionStatus": "OPT_IN"
},
{
"topicName": "Cycling",
"subscriptionStatus": "OPT_OUT"
}
]
}
{
"emailAddress": "example2@amazon.com",
"unsubscribeAll": true,
"topicPreferences": [
{
"topicName": "Sports",
"subscriptionStatus": "OPT_OUT"
},
{
"topicName": "Cycling",
"subscriptionStatus": "OPT_OUT"
}
]
}
```
In the preceding examples, replace *example1@amazon.com* and *example2@amazon.com* with the email addresses you want to add to the contact list. Replace the `attributesData` values with the values specific to the contact. Additionally, replace *Sports* and *Cycling* with the `topicName` that applies to your contact. The acceptable `topicPreferences` are *OPT\$1IN* and *OPT\$1OUT*.
The following attributes are supported when uploading your contacts into an Amazon S3 object in either CSV or JSON format:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ses/latest/dg/sending-email-list-management.html)
+ Give SES permission to read the Amazon S3 object.
When applied to an Amazon S3 bucket, the following policy gives SES permission to read that bucket. For more information about attaching policies to Amazon S3 buckets, see [Using Bucket Policies and User Policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-iam-policies.html) in the *Amazon Simple Storage Service User Guide*.
+ Give SES permission to use your AWS KMS key.
If the Amazon S3 object is encrypted with an AWS KMS key, you need to give Amazon SES permission to use the KMS key. SES can only attain permission from a customer managed key, not a default KMS key. You must give SES permission to use the customer managed key by adding a statement to the key's policy.
Paste the following policy statement into the key policy to permit SES to use your customer managed key.
```
{
"Sid": "AllowSESToDecrypt",
"Effect": "Allow",
"Principal": {
"Service":"ses.amazonaws.com"
},
"Action": [
"kms:Decrypt",
],
"Resource": "*"
}
```
+ Use the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) operation in the SES API v2.
**Note**
The following example assumes that you've already installed the AWS CLI. For more information about installing and configuring the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/).
At the command line, enter the following command. Replace *s3bucket* withe the name of the Amazon S3 bucket and *s3object* with the name of the Amazon S3 object name.
```
aws sesv2 create-import-job --import-destination ContactListDestination={ContactListName=ExampleContactListName,ContactListImportAction=PUT} --import-data-source S3Url="s3://s3bucket/s3object",DataFormat=CSV
```
## List management walkthrough with examples
The following walkthrough provides examples of how you can use list management to list your contacts, utilize `ListManagementOptions` to specify a contact list and topic name in your email, and how to insert unsubscribe links.
1. **List contacts by using the AWS CLI** – You can use the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html) operation to retrieve a list of all your contacts who have subscribed to a particular topic, in conjunction with the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) operation, which allows you to send them emails.
At the command line, enter the following command:
```
aws sesv2 list-contacts --cli-input-json file://LIST-CONTACTS-JSON
```
In the preceding command, replace *LIST-CONTACTS-JSON* with the path to your JSON file for your [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html) request.
An example `ListContacts` input JSON file for the request is as follows:
```
{
"ContactListName": "ExampleContactListName",
"Filter": {
"FilteredStatus": "OPT_IN",
"TopicFilter": {
"TopicName": "Cycling",
"UseDefaultIfPreferenceUnavailable": true
}
},
"PageSize": 50
}
```
The `FilteredStatus` shows the subscription status for which you want to filter, which is either `OPT_IN` or `OPT_OUT`.
The `TopicFilter` is an optional filter which specifies which topic you want results for, and in the example above, that is "*Cycling*."
`UseDefaultIfPreferenceUnavailable` can have a value of `true` or `false`. If `true`, the topic default preference will be used if the contact doesn’t have any explicit preference for a topic. If `false`, only contacts with an explicitly set preference are considered for filtering.
1. **Send mail with `ListManagementOptions` enabled** – After listing the contacts in your list using the above [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html) operation, you can use the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) operation to send emails to each of your contacts by utilizing the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) header to specify your contact list and topic name.
To use `ListManagementOptions` with the `SendEmail` operation, include the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) and [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) to which the email belongs (the `topicName` is optional):
```
ListManagementOptions:
String contactListName
String topicName
```
If you include `ListManagementOptions` in your `SendEmail` request to a recipient email address that is not on your contact list, then a contact will be created on your list automatically.
SES will issue a bounce event for a message that is sent to an unsubscribed contact on your contact list, which means you won’t need to update your `SendEmail` requests to avoid sending to contacts who have unsubscribed.
1. **Indicate the location for your unsubscribe links** – When utilizing [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) you have the option to enable SES to add unsubscribe footer links in your email using the `{{amazonSESUnsubscribeUrl}}` placeholder to specify where SES needs to insert the unsubscribe URL. Placeholder replacement is supported only for HTML and TEXT content types. You can include the placeholder two times maximum. If used more than two times, only the first two occurrences are replaced. For more information, see [Using subscription management](sending-email-subscription-management.md).
Alternatively, if you're using the SMTP interface to send email, you can use the `X-SES-LIST-MANAGEMENT-OPTIONS` header to specify a list and topic name.
To specify a list and topic name while sending email using the SMTP interface, add the following email header to your message:
`X-SES-LIST-MANAGEMENT-OPTIONS: {contactListName}; topic={topicName}`
# Using subscription management
Amazon SES provides a subscription management capability, in which Amazon SES automatically enables the unsubscribe links in every outgoing email when you specify the `contactListName` and `topicName` within [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) in the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) operation request.
If a contact unsubscribes from a particular topic or list, Amazon SES does not allow email sending to the contact for that topic or list in the future.
**Note**
Amazon SES subscription management supports *Bulk Sender Requirements* as enforced by many email service providers, see *Section 2* in [An Overview of Bulk Sender Changes](https://aws.amazon.com//blogs/messaging-and-targeting/an-overview-of-bulk-sender-changes-at-yahoo-gmail/) for more information.
Subscription management is available for those using [Easy DKIM in Amazon SES](send-email-authentication-dkim-easy.md), but it’s not possible for Amazon SES to add the unsubscribe links to your email for senders who are signing emails themselves before calling Amazon SES.
For information about list management and how to use it, including retrieving a list of all your contacts who have subscribed to a particular topic, see [Using list management](sending-email-list-management.md).
## Subscription management overview
You should consider the following factors when you use subscription management:
+ Subscription management will be fully managed by Amazon SES. This means that Amazon SES receives unsubscribe emails and requests from the unsubscribe webpage and then updates the contact’s preference in your list. You can receive unsubscribe notifications using configuration set notifications. For more information about configuration sets, see [Using configuration sets in Amazon SES](using-configuration-sets.md).
+ You need to specify the contact list while sending the email. Subscription management via the `List-Unsubscribe` header and `ListManagementOptions` footer links will be handled accordingly.
+ Amazon SES adds support for the `List-Unsubscribe` header standards, which will enable email clients and inbox providers to display an unsubscribe link at the top of the email *if they support it* - not all email service providers support these headers.
+ `List-Unsubscribe` headers follow the following behavior:
+ If a contact clicks the unsubscribe link in an email which has both the contact list and topic specified, then the contact will be unsubscribed only from that specific topic.
+ If the topic is not specified, then the contact will be unsubscribed from all the topics in the list.
+ Contacts will be taken to an unsubscribe landing page when they click an unsubscribe link in the email footer.
+ The unsubscribe landing page will give contacts an option to update their preferences, meaning `OPT_IN` or `OPT_OUT`, for all the topics in a particular list. The landing page also gives an option to unsubscribe from all topics in the list.
+ If using [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html), you must include the `{{amazonSESUnsubscribeUrl}}` placeholder in your emails to indicate where Amazon SES needs to insert the unsubscribe URL. You can include the placeholder two times maximum. If used more than two times, only the first two occurrences are replaced.
+ The `List-Unsubscribe` header and `ListManagementOptions` footer links are added only if the email is being sent to a single recipient.
+ For transactional emails where you don't want contacts to be able to unsubscribe, you can omit the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) field with your [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) request.
## Unsubscribe header considerations
Subscription management through an unsubscribe link is enabled when the email contains the following headers:
`List-Unsubscribe`
`List-Unsubscribe-Post`
When you use Amazon SES's subscription management, [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html), Amazon SES will override these headers if they are present in the email.
Recipients who unsubscribe by clicking the link produced by these headers will have a different experience depending on their email client or inbox provider because some providers do not recognize the `List-Unsubscribe` and `List-Unsubscribe-Post` headers; email sent to recipients using such providers will not see the Unsubscribe link.
Recipients whose email client recognizes these headers will see the Unsubscribe link and will be able to unsubscribe via the link but will not have the option of choosing which topics they unsubscribe from, and will simply be unsubscribed from the topic to which the email was sent.
For more information about the `List-Unsubscribe` header, see [RFC 2369](https://tools.ietf.org/html/rfc2369), and for the `List-Unsubscribe-Post` header, see [RFC 8058](https://tools.ietf.org/html/rfc8058).
**Note**
Amazon SES supports *one-click unsubscribe* in accordance with *Bulk Sender Requirements* as enforced by many email service providers, see [ Using one-click unsubscribe with Amazon SES](https://aws.amazon.com//blogs/messaging-and-targeting/using-one-click-unsubscribe-with-amazon-ses/) for more information.
## Adding an unsubscribe footer link
You will need to use the `{{amazonSESUnsubscribeUrl}}` placeholder in templated and non-templated emails to specify where Amazon SES needs to insert the unsubscribe URL.
Placeholder replacement is supported only for HTML and TEXT content types.
You can include the placeholder two times maximum. If used more than two times, only the first two occurrences are replaced.
**Note**
The `{{amazonSESUnsubscribeUrl}}` placeholder can only be used if [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) is specified as a header while using the [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) operation or X-SES-LIST-MANAGEMENT-OPTIONS is specified as a header while using the SMTP interface. (Not to be confused with the `List-Unsubscribe` or `List-Unsubscribe-Post` headers which are not dependent on `ListManagementOptions` and can be used by themselves.)