使用列表管理

Amazon SES 提供列表管理功能，这意味着客户可以管理自己的邮件列表，称为联系人列表。联系人列表让您能够存储订阅了一个或多个特定主题的所有联系人。联系人是接收您的电子邮件的最终用户。主题是列表中的兴趣组、主题或标签。列表可以包含多个主题。

通过使用 Amazon SES API v2 中的 ListContacts 操作，您可以检索订阅了特定主题的所有联系人的列表，而您可以使用 SendEmail 操作向这些联系人发送电子邮件。

有关订阅管理的更多信息，请参阅使用订阅管理。

列表管理概述

在使用列表管理时，您应注意以下事项：

您可以在创建列表时指定列表主题。
每个 AWS 账户只允许使用一个联系人列表。
一个列表可以包含最多 20 个主题。
您可以更新现有联系人列表，包括向列表添加新主题、在列表中添加或删除联系人，以及更新列表或主题的联系人首选项。
您可以更新主题元数据，例如主题显示名称或描述。
您可以获取联系人列表中的联系人、订阅某个主题的联系人、取消订阅某个主题的联系人以及取消订阅列表中所有主题的联系人的列表。
您可以使用 CreateImportJob API 将您的现有联系人列表导入到 Amazon SES。
如果有电子邮件发送到您的联系人列表上已取消订阅的联系人，那么 Amazon SES 将退回该邮件。有关更多信息，请参阅使用订阅管理。
每个联系人都可以有关联的属性，您可以使用这些属性来存储有关该联系人的信息。

配置列表管理

您可以使用以下操作来配置列表管理功能。有关联系人列表和联系人操作的完整列表，请参阅 Amazon SES API v2 参考。

创建联系人列表

您可以使用 Amazon SES API v2 中的 CreateContactList 操作来创建联系人列表。您可以使用 AWS CLI 轻松快速地配置此设置。有关安装和配置 AWS CLI 的更多信息，请参阅 AWS Command Line Interface 用户指南。

使用 AWS CLI 来创建联系人列表

在命令行输入以下命令：


aws sesv2 create-contact-list --cli-input-json file://CONTACT-LIST-JSON

在前面的命令中，将 CONTACT-LIST-JSON 替换为您的 CreateContactList 请求的 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"
     }
    ]
}

创建联系人

您可以使用 Amazon SES API v2 中的 CreateContact 操作来创建联系人。您可以使用 AWS CLI 轻松快速地配置此设置。有关安装和配置 AWS CLI 的更多信息，请参阅 AWS Command Line Interface 用户指南。

使用 AWS CLI 来创建联系人

在命令行输入以下命令：
```
aws sesv2 create-contact --cli-input-json file://CONTACT-JSON
```
在前面的命令中，将 CONTACT-JSON 替换为您的 CreateContact 请求的 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 对象中，然后使用 Amazon SES API v2 中的 CreateImportJob 操作，或者使用 SES 控制台。有关更多信息，请参阅将电子邮件地址批量添加到账户级黑名单。

在导入您的联系人之前，您应该创建一个联系人列表。

注意

您可以将最多 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_IN 和 OPT_OUT。

以 CSV 或 JSON 格式将您的联系人上传到 Amazon S3 对象中时，支持以下属性：

属性	描述
`emailAddress`	联系人的电子邮件地址。此字段为必填字段。
`unsubscribeAll`	一个布尔值状态，表示联系人是否已取消订阅所有联系人列表主题。
`topicPreferences`	联系人选择加入或选择退出主题的首选项。
`attributesData`	附加到联系人的属性数据。

向 Amazon SES 授予对 Amazon S3 对象的读取权限。

以下策略应用于 Amazon S3 存储桶时，会向 Amazon SES 授予对该存储桶的读取权限。有关将策略附加到 Amazon S3 的存储桶的更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的使用存储桶策略和用户策略。


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSESGet",
            "Effect": "Allow",
            "Principal": {
                "Service": "ses.amazonaws.com"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::BUCKET-NAME/OBJECT-NAME",
            "Condition": {
                "StringEquals": {
                    "aws:Referer": "AWSACCOUNTID"
                }
            }
        }
    ]
}

为 Amazon SES 提供使用您的 AWS KMS 密钥的权限。

如果 Amazon S3 对象使用 AWS KMS 密钥加密，则需要向 Amazon SES 授予对 KMS 密钥的使用权限。Amazon SES 只能从客户托管式密钥获得权限，而不是原定设置的 KMS 密钥。您必须向 Amazon SES 提供客户托管式密钥的使用权限，方法是在密钥策略中添加一条语句。

将以下策略语句粘贴到密钥策略中，以允许 Amazon SES 使用您的客户托管式密钥。
```
{
   "Sid": "AllowSESToDecrypt", 
   "Effect": "Allow",
   "Principal": {
       "Service":"ses.amazonaws.com"
   },
   "Action": [
       "kms:Decrypt", 
   ],
   "Resource": "*"
}
```
使用 Amazon SES API v2 中的 CreateImportJob 操作。

注意

以下示例假定您已安装 AWS CLI。有关安装和配置 AWS CLI 的更多信息，请参阅 AWS Command Line Interface 用户指南。

在命令行输入以下命令。将 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 在电子邮件中指定联系人列表和主题名称，以及如何插入取消订阅链接。

使用 AWS CLI 列出联系人 – 您可以使用 ListContacts 操作结合 SendEmail 操作（允许您向联系人发送电子邮件）来检索订阅了特定主题的所有联系人的列表。

在命令行输入以下命令：
```
aws sesv2 list-contacts --cli-input-json file://LIST-CONTACTS-JSON
```
在前面的命令中，将 LIST-CONTACTS-JSON 替换为您的 ListContacts 请求的 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，则只考虑筛选具有明确设置的首选项的联系人。
在启用 ListManagementOptions 的情况下发送邮件–使用上述 ListContacts 操作在列表中列出联系人后，您可以使用 SendEmail 操作，通过 ListManagementOptions 标头指定联系人列表和主题名，以向每个联系人发送电子邮件。

要将 ListManagementOptions 与 SendEmail 操作一起使用，请包括电子邮件所属的 contactListName 和 topicName（可选）：
```
ListManagementOptions:
    String contactListName
    String topicName
                
```
如果您在发送给不在您联系人列表中的收件人电子邮件地址的 SendEmail 请求中包含 ListManagementOptions，那么您的列表中会自动创建联系人。

如果将电子邮件发送给您的联系人列表中已取消订阅的联系人，那么 Amazon SES 将退回该电子邮件，这意味着您不需要更新您的 SendEmail 请求即可避免向已取消订阅的联系人发送邮件。
指明取消订阅链接的位置 – 利用 ListManagementOptions 时，您可以通过使用 {{amazonSESUnsubscribeUrl}} 占位符指定 Amazon SES 需要插入取消订阅 URL 的位置，选择让 SES 在电子邮件中添加取消订阅脚注链接。仅支持 HTML 和 TEXT 内容类型的占位符替换。您可以最多两次包含该占位符。如果使用了两次以上，那么仅替换前两次出现的占位符。有关更多信息，请参阅使用订阅管理。

或者，如果使用 SMTP 接口发送电子邮件，则可以使用 X-SES-LIST-MANAGEMENT-OPTIONS 标头指定列表和主题名称。

要指定在使用 SMTP 接口发送电子邮件时的列表和主题名称，请将以下电子邮件标头添加到您的邮件：

X-SES-LIST-MANAGEMENT-OPTIONS: {contactListName}; topic={topicName}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

使用配置集级别的抑制

使用订阅管理