本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用範本透過 Amazon SES API 傳送個人化電子郵件
<a name="send-personalized-email-api"></a>

在 Amazon SES 中，您可以使用*預存範本*或使用*內嵌範本*來傳送範本電子郵件。
+ **存放範本** – 是指使用 Amazon SES v2 API 中的 `CreateEmailTemplate`操作，在 Amazon SES中建立和儲存[https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Template.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Template.html)的資源。範本包含電子郵件的主旨和內文，其中包含與撰寫內容內嵌的變數 （預留位置）。呼叫 `SendEmail`或 `SendBulkEmail` v2 API 操作時，會提供存放範本的名稱，以及範本中預留位置變數的動態資料。

  *儲存的範本*可以輕鬆重複使用，並在傳送類似類型的電子郵件時節省您的時間和精力。您不需要從頭開始建立每封電子郵件，只需建立基本結構和設計一次，只需更新範本中的動態內容即可。
+ **內嵌範本** – 不使用 `Template` 資源，而是在呼叫 `SendEmail`或 `SendBulkEmail` v2 API 操作時，提供包含變數 （預留位置） 的電子郵件主旨和內文與寫入內容以及這些預留位置變數的值。

  *內嵌範本*可讓您直接在應用程式邏輯中包含範本內容，藉此簡化大量電子郵件的傳送程序，無需管理 SES 帳戶中的範本資源，並簡化整合程序。它們不會計入每個 的 20，000 個範本限制 AWS 區域。

使用*預存範本*時，適用下列限制：
+ 每個範本最多可以建立 20，000 個電子郵件範本 AWS 區域。
+ 每個範本大小最多可達 500 KB，包括文字和 HTML 部分。

使用*內嵌範本*時，適用下列限制：
+ 每個輸入 JSON 檔案的大小最多可達 1 MB，包括文字和 HTML 部分。

下列適用於*預存*和*內嵌範本*：
+ 可使用的替換變數數量沒有限制。
+ 每次呼叫 `SendBulkEmail`操作時，您最多可以傳送電子郵件到 50 個目的地物件。[https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Destination.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Destination.html) 物件可包含在 **ToAddresses**、**CcAddresses** 和 **BccAddresses** 中定義的多個收件人。您可以在對 v2 API 的單一呼叫中聯絡的目的地數量可能受到您帳戶的最大傳送速率的限制。如需詳細資訊，請參閱[管理您的 Amazon SES 傳送限制](manage-sending-quotas.md)。

本章包含使用*預存範本*和*內嵌範本*的範例程序。

**注意**  
本節中的程序假設您已安裝並設定 AWS CLI。如需安裝和設定 的詳細資訊 AWS CLI，請參閱 [AWS Command Line Interface 使用者指南](https://docs.aws.amazon.com/cli/latest/userguide/)。

## （選用） 第 1 部分：設定轉譯失敗事件通知
<a name="send-personalized-email-set-up-notifications"></a>

 若您傳送包含無效個人化內容的電子郵件，Amazon SES 一開始雖然會接受該訊息，但將無法遞送它。因此，如果您計劃傳送個人化電子郵件，您應該設定 SES 透過 Amazon SNS 傳送轉譯失敗事件通知。當您收到轉譯失敗事件通知時，可找出哪些訊息包含無效的內容，修正問題後再次傳送訊息。

本節的程序為選用，但強烈建議使用。

**若要設定轉譯失敗事件通知**

1. 建立 Amazon SNS 主題。如需詳細資訊，請參閱 *Amazon Simple Notification Service 開發人員指南*中的[建立主題](https://docs.aws.amazon.com/sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html)。

1. 訂閱 Amazon SNS 主題。例如，如果您想要透過電子郵件接收轉譯失敗通知，請訂閱電子郵件端點 (也就是您的電子郵件地址) 至主題。

   如需詳細資訊，請參閱 *Amazon Simple Notification Service 開發人員指南*中的[訂閱主題](https://docs.aws.amazon.com/sns/latest/dg/SubscribeTopic.html)。

1. 完成 [為事件發佈設定 Amazon SNS 事件目的地](event-publishing-add-event-destination-sns.md) 中的程序，將組態集設定為將轉譯失敗事件發佈至 Amazon SNS 主題。

## （選用） 第 2 部分：建立電子郵件範本
<a name="send-personalized-email-create-template"></a>

如果您想要使用*預存範本*，本節將示範如何使用 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateEmailTemplate.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateEmailTemplate.html) SES v2 API 操作來建立範本。如果您想要使用*內嵌範本*，可以略過此步驟。

此程序假設您已安裝並設定 AWS CLI。如需安裝和設定 的詳細資訊 AWS CLI，請參閱 [AWS Command Line Interface 使用者指南](https://docs.aws.amazon.com/cli/latest/userguide/)。

**若要建立範本**

1. 在文字編輯器中，建立新的檔案，並視需要貼上下列程式碼進行自訂。

   ```
   {
       "TemplateName": "MyTemplate",
       "TemplateContent": {
           "Subject": "Greetings, {{name}}!",
           "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",
           "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"
       }
   }
   ```

   此程式碼包含下列屬性：
   + **TemplateName** – `Template` 資源的名稱。當您傳送電子郵件時，請參考此名稱。
   + **TemplateContent** – 下列屬性的容器：
     + **主旨** – 電子郵件的主旨行。此屬性可能包含替換標籤。這些標籤使用以下格式：`{{tagname}}`。當您傳送電子郵件時，可以為每個目的地指定 `tagname` 的值。
     + **Html** – 電子郵件的 HTML 內文。此屬性可能包含替換標籤。上述範例包含兩個標籤：`{{name}}` 和 `{{favoriteanimal}}`。
     + **文字** – 電子郵件的文字內文。電子郵件用戶端未顯示 HTML 內容的收件人將看到此版本的電子郵件。此屬性也可能包含替代標籤。

1. 自訂上述範例以符合您的需求，然後將檔案儲存為 {{mytemplate.json}}。

1. 在命令列中輸入下列命令，以使用 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateEmailTemplate.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateEmailTemplate.html) v2 API 操作建立新的範本：

   ```
   aws sesv2 create-email-template --cli-input-json file://{{mytemplate.json}}
   ```

## 第 3 部分：傳送個人化電子郵件
<a name="send-personalized-email-api-operations"></a>

您可以使用下列兩個 SES v2 API 操作，使用*預存範本*或*內嵌範本*傳送電子郵件：
+ [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) 操作有助於將自訂電子郵件傳送至單一目的地物件。v2 API [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Destination.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Destination.html) 物件可以包含 *ToAddresses*、*CcAddresses* 和 *BccAddresses* 屬性。這些可以任意組合使用，並且可以包含將接收相同電子郵件的一或多個電子郵件地址。
+ [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendBulkEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendBulkEmail.html) 此操作有助於在對 v2 API 的單一呼叫中，將唯一電子郵件傳送至多個目的地物件。

本節提供如何使用 AWS CLI ，透過這兩種傳送操作來傳送範本電子郵件的範例。

### 將範本電子郵件傳送至單一目的地物件
<a name="send-templated-email-single-destination"></a>

您可以使用 [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_Destination.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Destination.html) 物件中的所有收件人將會收到相同的電子郵件。

**將範本電子郵件傳送至單一目的地物件**

1. 視您要使用*預存範本*或*內嵌範本*而定，選取個別的程式碼範例以貼到文字編輯器中，視需要進行自訂。

------
#### [ Stored template code example ]

   請注意，您在上一個步驟中建立的範本 *MyTemplate* 被參考為 `TemplateName` 參數的值。

   ```
   {
       "FromEmailAddress": "Mary Major <mary.major@example.com>",
       "Destination": {
           "ToAddresses": [
               "alejandro.rosalez@example.com", "jimmy.jet@example.com"
           ]
       },
       "Content": {
           "Template": {
               "TemplateName": "MyTemplate",
               "TemplateData": "{ \"name\":\"Alejandro\", \"favoriteanimal\": \"alligator\" }"
           }
       },
       "ConfigurationSetName": "ConfigSet"
   }
   ```

   此程式碼包含下列屬性：
   + **FromEmailAddress** – 寄件者的電子郵件地址。
   + **目的地** – 包含 *ToAddresses*、*CcAddresses* 和 *BccAddresses* 屬性中定義的電子郵件收件人的物件。這些可以任意組合使用，並且可以包含將接收相同電子郵件的一或多個電子郵件地址。
   + **TemplateName** – 要套用至電子郵件`Template`的資源名稱。
   + **TemplateData** - 包含鍵值對的逸出 JSON 字串。索引鍵對應至預存範本中`TemplateContent`屬性中定義的變數，例如 `{{name}}`。這些值代表取代變數的內容。
   + **ConfigurationSetName** - 傳送電子郵件時使用的組態集名稱。
**注意**  
建議您使用已設為發佈轉譯失敗事件至 Amazon SNS 的組態集。如需詳細資訊，請參閱[（選用） 第 1 部分：設定轉譯失敗事件通知](#send-personalized-email-set-up-notifications)。

------
#### [ Inline template code example ]

   請注意，`TemplateContent`屬性 （通常在*預存範本*中定義） 會與使之成為*內嵌範本*的 `TemplateData` 屬性*一起內嵌*定義。

   ```
   {
       "FromEmailAddress": "Mary Major <mary.major@example.com>",
       "Destination": {
           "ToAddresses": [
               "alejandro.rosalez@example.com", "jimmy.jet@example.com"
           ]
       },
       "Content": {
           "Template": {
               "TemplateContent": {
                   "Subject": "Greetings, {{name}}!",
                   "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",
                   "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"
               },
               "TemplateData": "{ \"name\":\"Alejandro\", \"favoriteanimal\": \"alligator\" }"
           }
       },
       "ConfigurationSetName": "ConfigSet"
   }
   ```

   此程式碼包含下列屬性：
   + **FromEmailAddress** – 寄件者的電子郵件地址。
   + **目的地** – 包含 *ToAddresses*、*CcAddresses* 和 *BccAddresses* 屬性中定義的電子郵件收件人的物件。這些可以任意組合使用，並且可以包含將接收相同電子郵件的一或多個電子郵件地址。
   + **TemplateContent** – 下列屬性的容器：
     + **主旨** – 電子郵件的主旨行。此屬性可能包含替換標籤。這些標籤使用以下格式：`{{tagname}}`。當您傳送電子郵件時，可以為每個目的地指定 `tagname` 的值。
     + **Html** – 電子郵件的 HTML 內文。此屬性可能包含替換標籤。上述範例包含兩個標籤：`{{name}}` 和 `{{favoriteanimal}}`。
     + **文字** – 電子郵件的文字內文。電子郵件用戶端未顯示 HTML 內容的收件人將看到此版本的電子郵件。此屬性也可能包含替代標籤。
   + **TemplateData** - 包含鍵值對的逸出 JSON 字串。索引鍵會對應至此檔案中`TemplateContent`屬性中定義的變數，例如 `{{name}}`。這些值代表取代變數的內容。
   + **ConfigurationSetName** - 傳送電子郵件時使用的組態集名稱。
**注意**  
建議您使用已設為發佈轉譯失敗事件至 Amazon SNS 的組態集。如需詳細資訊，請參閱[（選用） 第 1 部分：設定轉譯失敗事件通知](#send-personalized-email-set-up-notifications)。

------

1. 自訂上述範例以符合您的需求，然後將檔案儲存為 {{myemail.json}}。

1. 在命令列輸入下列 v2 API 命令來傳送電子郵件：

   ```
   aws sesv2 send-email --cli-input-json file://{{myemail.json}}
   ```

### 將範本電子郵件傳送至多個目的地物件
<a name="send-templated-email-multiple-destinations"></a>

您可以使用 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendBulkEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendBulkEmail.html)操作，在對 SES v2 API 的單一呼叫中傳送電子郵件至多個目的地物件。SES 會傳送唯一的電子郵件給每個[https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Destination.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_Destination.html)物件中的收件人。

**將範本電子郵件傳送至多個目的地物件**

1. 根據您想要使用*預存範本*或*內嵌範本*，選取個別的程式碼範例以貼到文字編輯器中，並根據需要進行自訂。

------
#### [ Stored template code example ]

   請注意，您在上一個步驟中建立的範本 *MyTemplate* 被參考為 `TemplateName` 參數的值。

   ```
   {
       "FromEmailAddress": "Mary Major <mary.major@example.com>",
       "DefaultContent": {
           "Template": {
               "TemplateName": "MyTemplate",
               "TemplateData": "{ \"name\":\"friend\", \"favoriteanimal\":\"unknown\" }"
           }
       },
       "BulkEmailEntries": [
           {
               "Destination": {
                   "ToAddresses": [
                       "anaya.iyengar@example.com"
                   ]
               },
               "ReplacementEmailContent": {
                   "ReplacementTemplate": {
                       "ReplacementTemplateData": "{ \"name\":\"Anaya\", \"favoriteanimal\":\"angelfish\" }"
                   }
               }
           },
           {
               "Destination": {
                   "ToAddresses": [
                       "liu.jie@example.com"
                   ]
               },
               "ReplacementEmailContent": {
                   "ReplacementTemplate": {
                       "ReplacementTemplateData": "{ \"name\":\"Liu\", \"favoriteanimal\":\"lion\" }"
                   }
               }
           },
           {
               "Destination": {
                   "ToAddresses": [
                       "shirley.rodriguez@example.com"
                   ]
               },
               "ReplacementEmailContent": {
                   "ReplacementTemplate": {
                       "ReplacementTemplateData": "{ \"name\":\"Shirley\", \"favoriteanimal\":\"shark\" }"
                   }
               }
           },
           {
               "Destination": {
                   "ToAddresses": [
                       "richard.roe@example.com"
                   ]
               },
               "ReplacementEmailContent": {
                   "ReplacementTemplate": {
                       "ReplacementTemplateData": "{}"
                   }
               }
           }
       ],
       "ConfigurationSetName": "ConfigSet"
   }
   ```

   此程式碼包含下列屬性：
   + **FromEmailAddress** – 寄件者的電子郵件地址。
   + **DefaultContent** – 包含 `TemplateName`和 物件的 JSON `TemplateData` 物件。
   + **TemplateName** – 要套用至電子郵件`Template`的資源名稱。
   + **TemplateData** – 在 `ReplacementTemplateData` 屬性`{}`中包含物件`ReplacementEmailContent`包含空白 JSON 物件 時將使用的鍵值對。
   + **BulkEmailEntries** – 包含一或多個`Destination`物件的陣列。
   + **目的地** – 包含 *ToAddresses*、*CcAddresses* 和 *BccAddresses* 屬性中定義的電子郵件收件人的物件。這些可以任意組合使用，並且可以包含將接收相同電子郵件的一或多個電子郵件地址。
   + **ReplacementTemplateData** – 包含鍵值對的逸出 JSON 字串。索引鍵對應至範本中的變數，例如 `{{name}}`。值則代表替換電子郵件中變數的內容。（如果此處的 JSON 字串空白，以 表示`{}`，則會使用 `DefaultContent` 物件內 `TemplateData` 屬性中定義的鍵/值對。)
   + **ConfigurationSetName** - 傳送電子郵件時使用的組態集名稱。
**注意**  
建議您使用已設為發佈轉譯失敗事件至 Amazon SNS 的組態集。如需詳細資訊，請參閱[（選用） 第 1 部分：設定轉譯失敗事件通知](#send-personalized-email-set-up-notifications)。

------
#### [ Inline template code example ]

   請注意，`TemplateContent`屬性 （通常在*預存範本*中定義） 會與使之成為*內嵌範本*的 `TemplateData` 屬性*一起內嵌*定義。

   ```
   {
       "FromEmailAddress": "Mary Major <mary.major@example.com>",
       "DefaultContent": {
           "Template": {
               "TemplateContent": {
                   "Subject": "Greetings, {{name}}!",
                   "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",
                   "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"
               },
               "TemplateData": "{ \"name\":\"friend\", \"favoriteanimal\":\"unknown\" }"
           }
       },
       "BulkEmailEntries": [
           {
               "Destination": {
                   "ToAddresses": [
                       "anaya.iyengar@example.com"
                   ]
               },
               "ReplacementEmailContent": {
                   "ReplacementTemplate": {
                       "ReplacementTemplateData": "{ \"name\":\"Anaya\", \"favoriteanimal\":\"angelfish\" }"
                   }
               }
           },
           {
               "Destination": {
                   "ToAddresses": [
                       "liu.jie@example.com"
                   ]
               },
               "ReplacementEmailContent": {
                   "ReplacementTemplate": {
                       "ReplacementTemplateData": "{ \"name\":\"Liu\", \"favoriteanimal\":\"lion\" }"
                   }
               }
           },
           {
               "Destination": {
                   "ToAddresses": [
                       "shirley.rodriguez@example.com"
                   ]
               },
               "ReplacementEmailContent": {
                   "ReplacementTemplate": {
                       "ReplacementTemplateData": "{ \"name\":\"Shirley\", \"favoriteanimal\":\"shark\" }"
                   }
               }
           },
           {
               "Destination": {
                   "ToAddresses": [
                       "richard.roe@example.com"
                   ]
               },
               "ReplacementEmailContent": {
                   "ReplacementTemplate": {
                       "ReplacementTemplateData": "{}"
                   }
               }
           }
       ],
       "ConfigurationSetName": "ConfigSet"
   }
   ```

   此程式碼包含下列屬性：
   + **FromEmailAddress** – 寄件者的電子郵件地址。
   + **DefaultContent** – 包含 `TemplateContent`和 物件的 JSON `TemplateData` 物件。
   + **TemplateContent** – 下列屬性的容器：
     + **主旨** – 電子郵件的主旨行。此屬性可能包含替換標籤。這些標籤使用以下格式：`{{tagname}}`。當您傳送電子郵件時，可以為每個目的地指定 `tagname` 的值。
     + **Html** – 電子郵件的 HTML 內文。此屬性可能包含替換標籤。上述範例包含兩個標籤：`{{name}}` 和 `{{favoriteanimal}}`。
     + **文字** – 電子郵件的文字內文。電子郵件用戶端未顯示 HTML 內容的收件人將看到此版本的電子郵件。此屬性也可能包含替代標籤。
   + **TemplateData** – 包含金鑰/值對`{}`，如果`ReplacementEmailContent`物件在 `ReplacementTemplateData` 屬性中包含空的 JSON 物件 時將使用。
   + **BulkEmailEntries** – 包含一或多個`Destination`物件的陣列。
   + **目的地** – 包含 *ToAddresses*、*CcAddresses* 和 *BccAddresses* 屬性中定義的電子郵件收件人的物件。這些可以任意組合使用，並且可以包含將接收相同電子郵件的一或多個電子郵件地址。
   + **ReplacementTemplateData** – 包含鍵值對的逸出 JSON 字串。索引鍵會對應至此檔案中`TemplateContent`屬性中定義的變數，例如 `{{name}}`。值則代表替換電子郵件中變數的內容。（如果此處的 JSON 字串空白，以 表示`{}`，則會使用 `DefaultContent` 物件內 `TemplateData` 屬性中定義的鍵/值對。)
   + **ConfigurationSetName** - 傳送電子郵件時使用的組態集名稱。
**注意**  
建議您使用已設為發佈轉譯失敗事件至 Amazon SNS 的組態集。如需詳細資訊，請參閱[（選用） 第 1 部分：設定轉譯失敗事件通知](#send-personalized-email-set-up-notifications)。

------

1. 變更上一個步驟程式碼中的值以符合您的需求，然後將檔案儲存為 {{mybulkemail.json}}。

1. 在命令列輸入下列 v2 API 命令來傳送大量電子郵件：

   ```
   aws sesv2 send-bulk-email --cli-input-json file://{{mybulkemail.json}}
   ```