本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用列表管理
Amazon SES 提供列表管理功能，这意味着客户可以管理自己的邮件列表，称为联系人列表。*联系人列表*让您能够存储订阅了一个或多个特定主题的所有联系人。*联系人*是接收您的电子邮件的最终用户。*主题*是列表中的兴趣组、主题或标签。列表可以包含多个主题。
通过使用 Amazon SES API v2 中的 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html) 操作，您可以检索订阅了特定主题的所有联系人的列表，而您可以使用 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) 操作向这些联系人发送电子邮件。
有关订阅管理的更多信息，请参阅 [使用订阅管理](sending-email-subscription-management.md)。
## 列表管理概述
在使用列表管理时，您应注意以下事项：
+ 您可以在创建列表时指定列表主题。
+ 每人只允许有一份联系人名单 AWS 账户。
+ 一个列表可以包含最多 20 个主题。
+ 您可以更新现有联系人列表，包括向列表添加新主题、在列表中添加或删除联系人，以及更新列表或主题的联系人首选项。
+ 您可以更新主题元数据，例如主题显示名称或描述。
+ 您可以获取联系人列表中的联系人、订阅某个主题的联系人、取消订阅某个主题的联系人以及取消订阅列表中所有主题的联系人的列表。
+ 您可以使用 [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。
+ SES 将针对发送到您联系人列表中已取消订阅联系人的消息发出退回事件。有关更多信息，请参阅 [使用订阅管理](sending-email-subscription-management.md)。
+ 每个联系人都可以有关联的属性，您可以使用这些属性来存储有关该联系人的信息。
## 配置列表管理
您可以使用以下操作来配置列表管理功能。有关联系人列表和联系人操作的完整列表，请参阅 [Amazon SES API v2 参考](https://docs.aws.amazon.com/ses/latest/APIReference-V2/Welcome.html)。
### 创建联系人列表
您可以使用 SES API v2 中的 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html) 操作来创建联系人列表。您可以使用 AWS CLI轻松快速地配置此设置。有关安装和配置的更多信息 AWS CLI，请参阅《[AWS Command Line Interface 用户指南》](https://docs.aws.amazon.com/cli/latest/userguide/)。
**要创建联系人列表，请使用 AWS CLI**
+ 在命令行输入以下命令：
```
aws sesv2 create-contact-list --cli-input-json file://CONTACT-LIST-JSON
```
在前面的命令中，*CONTACT-LIST-JSON*替换为[https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html)请求的 JSON 文件的路径。
请求的 `CreateContactList` 输入 JSON 文件的示例如下：
```
{
"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"
}
]
}
```
### 创建联系人
您可以使用 SES API v2 中的 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html) 操作来创建联系人。您可以使用 AWS CLI轻松快速地配置此设置。有关安装和配置的更多信息 AWS CLI，请参阅《[AWS Command Line Interface 用户指南》](https://docs.aws.amazon.com/cli/latest/userguide/)。
**要创建联系人，请使用 AWS CLI**
+ 在命令行输入以下命令：
```
aws sesv2 create-contact --cli-input-json file://CONTACT-JSON
```
在前面的命令中，*CONTACT-JSON*替换为[https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html)请求的 JSON 文件的路径。
请求的 `CreateContact` 输入 JSON 文件的示例如下：
```
{
"ContactListName": "ExampleContactListName",
"EmailAddress": "example@amazon.com",
"UnsubscribeAll": false,
"TopicPreferences": [
{
"TopicName": "Sports",
"SubscriptionStatus": "OPT_IN"
}
],
"AttributesData": "{\"Name\": \"John\", \"Location\": \"Seattle\"}"
}
```
在以上示例中，`UnsubscribeAll` 值为 `false` 表明联系人未取消订阅所有主题，而值为 `true` 则意味着联系人已取消订阅所有主题。
`TopicPreferences` 包含有关联系人的主题订阅状态的信息。在前面的示例中，联系人选择订阅了“*Sports*”主题，那么他将收到“*Sports*”主题的所有电子邮件。
`AttributesData` 是一个 JSON 字段，您可以在其中放置有关我们的联系人的任何元数据。它必须是有效的 JSON 对象。
### 将联系人批量导入您的联系人列表
您可以手动批量添加地址，方法是首先将您的联系人上载到 Amazon S3 对象中，然后使用 SES API v2 中的 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) 操作，或者使用 SES 控制台。有关更多信息，请参阅 [将电子邮件地址批量添加到账户级黑名单](sending-email-suppression-list.md#sending-email-suppression-list-manual-add-bulk)。
在导入您的联系人之前，您应该创建一个联系人列表。
**注意**
每个联系人列表中最多可以添加 100 万个联系人 ImportJob。
要将联系人批量添加到您的联系人列表，请完成以下步骤。
+ 以 CSV 或 JSON 格式将您的联系人上传到 Amazon S3 对象中。
**CSV 格式**
上传到 Amazon S3 的文件的第一行应该是标题行。
使用 CSV 格式需要展平 `topicPreferences` 对象。`topicPreferences` 中的每个主题都将有单独的标题字段。
使用 CSV 格式将联系人批量添加到联系人列表的示例：
```
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 格式**
仅支持换行符分隔的 JSON 文件。在此格式中，每一行都是一个完整的 JSON 对象，其中包含一个联系人的信息。
将联系人批量添加到联系人列表的 JSON 格式示例：
```
{
"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"
}
]
}
```
在前面的示例中，将*example1@amazon.com*和*example2@amazon.com*替换为要添加到联系人列表的电子邮件地址。将 `attributesData` 值替换为特定于联系人的值。此外，请将*Sports*和 *Cycling*`topicName`，替换为适用于您的联系人的内容。可接受`topicPreferences`的是*OPT\$1IN*和*OPT\$1OUT*。
以 CSV 或 JSON 格式将您的联系人上传到 Amazon S3 对象中时，支持以下属性：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/ses/latest/dg/sending-email-list-management.html)
+ 向 SES 授予对 Amazon S3 对象的读取权限。
以下策略应用于 Amazon S3 存储桶时，会向 SES 授予对该存储桶的读取权限。有关将策略附加到 Amazon S3 的存储桶的更多信息，请参阅*《Amazon Simple Storage Service 用户指南》*中的[使用存储桶策略和用户策略](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-iam-policies.html)。
+ 授予 SES 使用您的 AWS KMS 密钥的权限。
如果 Amazon S3 对象使用 AWS KMS 密钥加密，则需要向 Amazon SES 授予使用 KMS 密钥的权限。SES 只能从客户托管式密钥获得权限，而不是原定设置的 KMS 密钥。您必须向 SES 提供客户托管式密钥的使用权限，方法是在密钥策略中添加一条语句。
将以下策略语句粘贴到密钥策略中，以允许 SES 使用您的客户托管式密钥。
```
{
"Sid": "AllowSESToDecrypt",
"Effect": "Allow",
"Principal": {
"Service":"ses.amazonaws.com"
},
"Action": [
"kms:Decrypt",
],
"Resource": "*"
}
```
+ 使用 SES API v2 中的 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) 操作。
**注意**
以下示例假定您已安装 AWS CLI。有关安装和配置的更多信息 AWS CLI，请参阅《[AWS Command Line Interface 用户指南》](https://docs.aws.amazon.com/cli/latest/userguide/)。
在命令行输入以下命令。替*s3bucket*换为 Amazon S3 存储桶的*s3object*名称和 Amazon S3 对象名称的名称。
```
aws sesv2 create-import-job --import-destination ContactListDestination={ContactListName=ExampleContactListName,ContactListImportAction=PUT} --import-data-source S3Url="s3://s3bucket/s3object",DataFormat=CSV
```
## 列出管理演练及示例
以下演练提供了一些示例，说明如何使用列表管理来列出联系人，如何使用 `ListManagementOptions` 在电子邮件中指定联系人列表和主题名称，以及如何插入取消订阅链接。
1. **使用列出联系人 AWS CLI** — 您可以使用该[https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html)操作来检索已订阅特定主题的所有联系人的列表，以及允许您向他们发送电子邮件的[https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html)操作。
在命令行输入以下命令：
```
aws sesv2 list-contacts --cli-input-json file://LIST-CONTACTS-JSON
```
在前面的命令中，*LIST-CONTACTS-JSON*替换为[https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html)请求的 JSON 文件的路径。
请求的 `ListContacts` 输入 JSON 文件的示例如下：
```
{
"ContactListName": "ExampleContactListName",
"Filter": {
"FilteredStatus": "OPT_IN",
"TopicFilter": {
"TopicName": "Cycling",
"UseDefaultIfPreferenceUnavailable": true
}
},
"PageSize": 50
}
```
`FilteredStatus` 显示您要筛选的订阅状态，即 `OPT_IN` 或 `OPT_OUT`。
`TopicFilter` 是一个可选的筛选器，它指定您希望获得其结果的主题，在以上示例中为“*Cycling*”。
`UseDefaultIfPreferenceUnavailable` 可以具有值 `true` 或 `false`。如果为 `true`，当联系人没有对主题的任何明确首选项时，将使用主题默认首选项。如果为 `false`，则只考虑筛选具有明确设置的首选项的联系人。
1. **在启用 `ListManagementOptions` 的情况下发送邮件**–使用上述 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html) 操作在列表中列出联系人后，您可以使用 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) 操作，通过 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) 标头指定联系人列表和主题名，以向每个联系人发送电子邮件。
要将 `ListManagementOptions` 与 `SendEmail` 操作一起使用，请包括电子邮件所属的 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) 和 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html)（`topicName` 可选）：
```
ListManagementOptions:
String contactListName
String topicName
```
如果您在发送给不在您联系人列表中的收件人电子邮件地址的 `SendEmail` 请求中包含 `ListManagementOptions`，那么您的列表中会自动创建联系人。
SES 将针对发送到您联系人列表中已取消订阅联系人的消息发出退回事件，这意味着您不需要更新您的 `SendEmail` 请求以避免向已取消订阅的联系人发送。
1. **指明取消订阅链接的位置**：利用 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) 时，您可以通过使用 `{{amazonSESUnsubscribeUrl}}` 占位符指定 SES 需要插入取消订阅 URL 的位置，选择让 SES 在电子邮件中添加取消订阅脚注链接。仅支持 HTML 和 TEXT 内容类型的占位符替换。您可以最多两次包含该占位符。如果使用了两次以上，那么仅替换前两次出现的占位符。有关更多信息，请参阅 [使用订阅管理](sending-email-subscription-management.md)。
或者，如果使用 SMTP 接口发送电子邮件，则可以使用 `X-SES-LIST-MANAGEMENT-OPTIONS` 标头指定列表和主题名称。
要指定在使用 SMTP 接口发送电子邮件时的列表和主题名称，请将以下电子邮件标头添加到您的邮件：
`X-SES-LIST-MANAGEMENT-OPTIONS: {contactListName}; topic={topicName}`