本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用清單管理功能
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
```
在上述命令中，以 [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 檔案路徑取代 *CONTACT-LIST-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
```
在上述命令中，以 [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 檔案路徑取代 *CONTACT-JSON*。
請求的 `CreateContact` 輸入 JSON 檔案範例如下:
```
{
"ContactListName": "ExampleContactListName",
"EmailAddress": "example@amazon.com",
"UnsubscribeAll": false,
"TopicPreferences": [
{
"TopicName": "Sports",
"SubscriptionStatus": "OPT_IN"
}
],
"AttributesData": "{\"Name\": \"John\", \"Location\": \"Seattle\"}"
}
```
在上述範例中，`false` 的值 `UnsubscribeAll` 顯示聯絡人尚未取消訂閱所有主題，而值 `true` 表示聯絡人已取消訂閱所有主題。
`TopicPreferences` 包含聯絡人主題訂閱狀態的相關資訊。在上述範例中，聯絡人已選擇加入「*運動*」主題，且會收到「*運動*」主題的所有電子郵件。
`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)。
您應該先建立聯絡人清單再匯入聯絡人。
**注意**
每個 ImportJob 最多可以將一百萬個聯絡人新增至聯絡人清單。
若要將大量聯絡人新增至聯絡人清單，請完成下列步驟。
+ 以 CSV 或 JSON 格式將聯絡人清單上傳到 Amazon S3 物件中。
**CSV format (CSV 格式)**
上傳到 Amazon S3 的檔案的第一行應該是標頭行。
`topicPreferences` 物件需要針對 CSV 格式扁平化。`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 format (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` 值。此外，請以適用於您聯絡人的 `topicName` 取代 *Sports* 和 *Cycling*。可接受的 `topicPreferences` 為 *OPT\$1IN* 和 *OPT\$1OUT*。
以 CSV 或 JSON 格式將聯絡人上傳到 Amazon S3 物件時，支援下列屬性：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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
```
在上述命令中，以 [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 檔案路徑取代 *LIST-CONTACTS-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. **指出取消訂閱連結的位置** – 使用 SES 時，[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 的位置。預留位置取代功能僅支援 HTML 與 TEXT 內容類型。您最多可以包含預留位置兩次。如果使用兩次以上，只會取代一開始的兩次。如需詳細資訊，請參閱[使用訂閱管理功能](sending-email-subscription-management.md)。
或者，若您使用 SMTP 介面傳送電子郵件，您也可以使用 `X-SES-LIST-MANAGEMENT-OPTIONS` 標頭來指定清單和主題名稱。
若要在使用 SMTP 介面傳送電子郵件時指定清單和主題名稱，請在電子郵件中新增下列電子郵件標題：
`X-SES-LIST-MANAGEMENT-OPTIONS: {contactListName}; topic={topicName}`