SESv2 Coupon Newsletter spec (awsdocs#6248)

* SESv2 Coupon Newsletter README, SPECIFICATION, and sample files. This workflow demonstrates how to use the Amazon Simple Email Service (SES) v2 to send a coupon newsletter to a list of contacts.
DavidSouther · Mar 27, 2024 · c09a621 · c09a621
1 parent 216204c
commit c09a621
Show file tree

Hide file tree

Showing 7 changed files with 263 additions and 0 deletions.
diff --git a/workflows/sesv2_weekly_mailer/README.md b/workflows/sesv2_weekly_mailer/README.md
@@ -0,0 +1,65 @@
+# Amazon SES v2 Coupon Newsletter Workflow
+
+This workflow demonstrates how to use the Amazon Simple Email Service (SES) v2 to send a coupon newsletter to a list of contacts. It covers the following key steps:
+
+1. **Prepare the Application**
+
+   - Create a verified email identity for the "send/reply" email addresses.
+   - Create a contact list to store the newsletter subscribers.
+
+2. **Gather Subscriber Email Addresses**
+
+   - Allow subscribers to sign up for the newsletter by providing their email addresses.
+   - Send a welcome email to each new subscriber.
+
+3. **Send the Coupon Newsletter**
+
+   - Create a template for the coupon newsletter.
+   - Retrieve the list of contacts (subscribers).
+   - Send individual emails with the coupon newsletter template to each subscriber.
+   - Include Unsubscribe links and headers to follow bulk email best practices.
+
+4. **Monitor and Review**
+
+   - Review dashboards and metrics in the AWS console for the newsletter campaign.
+
+5. **Clean up**
+
+   - Delete the template.
+   - Delete the contact list.
+   - Optionally delete the sender verified email identity.
+
+## Prerequisites
+
+Before running this workflow, ensure you have:
+
+- An AWS account with proper permissions to use Amazon SES v2.
+- A verified email identity (domain or email address) in Amazon SES.
+
+## AWS Services Used
+
+This workflow uses the following AWS services:
+
+- Amazon Simple Email Service (SES) v2
+
+## SES v2 Actions Used
+
+The workflow covers the following SES v2 API actions:
+
+- [`CreateContact`](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html)
+- [`CreateContactList`](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html)
+- [`CreateEmailIdentity`](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateEmailIdentity.html)
+- [`CreateEmailTemplate`](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateEmailTemplate.html)
+- [`ListContacts`](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html)
+- [`SendEmail`](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html) (with both Simple and Template formats)
+
+## Implementations
+
+This example is implemented in the following languages:
+
+- [Python](../../python/example_code/sesv2/scenarios/wkflw-sesv2-mailer/README.md)
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0
diff --git a/workflows/sesv2_weekly_mailer/SPECIFICATION.md b/workflows/sesv2_weekly_mailer/SPECIFICATION.md
@@ -0,0 +1,90 @@
+# SES v2 Coupon Newsletter Workflow Specification
+
+Use the Amazon Simple Email Service (SES) v2 API to manage a subscription list for a weekly newsletter.
+
+## Prepare the Application
+
+1. Create an email identity.
+   - Request a `verified email` address from the user. This will be used as the `from` address, and the user will need to click a verification link in their email before continuing to part 3.
+   - Operation: **CreateEmailIdentity**
+     - `EmailIdentity`: Value of the `verified email` given by the user.
+2. Create a contact list with the name `weekly-coupons-newsletter`.
+   - Operation: **CreateContactList**
+     - `ContactListName`: `weekly-coupons-newsletter`
+
+## Gather Subscriber Email Addresses
+
+1. Prompt the user to enter a base email address for subscribing to the newsletter.
+   - For testing purposes, this workflow uses a single email address with [subaddress extensions](https://www.rfc-editor.org/rfc/rfc5233.html) (e.g., `[email protected]`, `[email protected]`, etc., also known as [plus addressing](https://en.wikipedia.org/wiki/Email_address#:~:text=For%20example%2C%20the%20address%20joeuser,sorting%2C%20and%20for%20spam%20control.)).
+   - Create 3 variants of this email address as `{user email}+ses-weekly-newsletter-{i}@{user domain}`.
+   - `{user-email}` is the portion up to the first `@` (0x40, dec 64). The `{user domain}` is everything after the first `@`.
+2. For each email address created:
+   1. Create a new contact with the provided email address in the `weekly-coupons-newsletter` contact list.
+      - Operation: **CreateContact**
+        - `ContactListName`: `weekly-coupons-newsletter`
+        - `EmailAddress`: The email address provided by the user.
+   2. Send a welcome email to the new contact using the content from the `welcome.html` file.
+      - Operation: **SendEmail**
+        - `FromEmailAddress`: Retrieve the value from the `VERIFIED_EMAIL_ADDRESS` environment variable.
+        - `Destination.ToAddresses`: The email address provided by the user.
+        - `Content.Simple.Subject.Data`: "Welcome to the Weekly Coupons Newsletter"
+        - `Content.Simple.Body.Text.Data`: Read the content from the `welcome.txt` file.
+        - `Content.Simple.Body.Html.Data`: Read the content from the `welcome.html` file.
+
+## Send the Coupon Newsletter
+
+1. Create an email template named `weekly-coupons` with the following content:
+   - Subject: `Weekly Coupons Newsletter`
+   - HTML Content: Available in the `coupon-newsletter.html` file.
+   - Text Content: Available in the `coupon-newsletter.txt` file.
+   - The emails should include an [Unsubscribe](#) link, using the url `{{amazonSESUnsubscribeUrl}}`.
+   - Operation: **CreateEmailTemplate**
+     - `TemplateName`: `weekly-coupons`
+     - `TemplateContent`:
+       - `Subject`: `Weekly Coupons Newsletter`
+       - `HtmlPart`: Read from the `coupon-newsletter.html` file
+       - `TextPart`: Read from the `coupon-newsletter.txt` file
+2. Retrieve the list of contacts from the `weekly-coupons-newsletter` contact list.
+   - Operation: **ListContacts**
+     - `ContactListName`: `weekly-coupons-newsletter`
+3. Send an email using the `weekly-coupons` template to each contact in the list.
+   - The email should include the following coupon items:
+     1. 20% off on all electronics
+     2. Buy one, get one free on books
+     3. 15% off on home appliances
+     4. Free shipping on orders over $50
+     5. 25% off on outdoor gear
+     6. 10% off on groceries
+   - Operation: **SendEmail**
+     - `Destination`:
+       - `ToAddresses`: One email address from the `ListContacts` response (each email address must get a unique `SendEmail` call for tracking and unsubscribe purposes).
+     - `Content`:
+       - `Template`:
+         - `TemplateName`: `weekly-coupons`
+         - `TemplateData`: JSON string representing an object with one key, `coupons`, which is an array of coupon items. Each coupon entry in the array should have one key, `details`, with the details of the coupon. See `sample_coupons.json`.
+     - `FromEmailAddress`: (Use the verified email address from step 1)
+     - `ListManagementOptions`:
+       - `ContactListName`: `weekly-coupons-newsletter` to correctly populate Unsubscribe headers and the `{{amazonSESUnsubscribeUrl}}` value.
+
+For more information on using templates with SES v2, refer to the [Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/dg/send-personalized-email-api.html).
+
+## Monitor and Review
+
+1. [Monitor your sending activity](https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-activity.html) using the [SES Homepage](https://console.aws.amazon.com/ses/home#/account) in the AWS console.
+
+## Clean up
+
+1. Delete the contact list. This operation also deletes all contacts in the list, without needing separate calls.
+   - Operation: **DeleteContactList**
+     - `ContactListName`: `weekly-coupons-newsletter`
+2. Delete the template.
+   - Operation: **DeleteEmailTemplate**
+     - `TemplateName`: `weekly-coupons`
+3. Delete the email identity (optional). Ask the user before performing this step, as they may not want to re-verify the email identity.
+   - Operation: **DeleteEmailIdentity**
+     - `EmailIdentity`: Value of the `verified email` given by the user in part 1.
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0
diff --git a/workflows/sesv2_weekly_mailer/coupon-newsletter.html b/workflows/sesv2_weekly_mailer/coupon-newsletter.html
@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Weekly Coupons Newsletter</title>
+    <style>
+      body {
+        font-family: Arial, sans-serif;
+        max-width: 600px;
+        margin: 0 auto;
+        padding: 20px;
+      }
+      h1 {
+        color: #333;
+      }
+      ul {
+        list-style-type: none;
+        padding: 0;
+      }
+      li {
+        background-color: #f5f5f5;
+        padding: 10px;
+        margin-bottom: 10px;
+        border-radius: 5px;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Weekly Coupons Newsletter</h1>
+    <p>Check out this week's hot deals and exclusive coupons!</p>
+    <ul>
+      {{#each coupons}}
+      <li>{{details}}</li>
+      {{/each}}
+    </ul>
+    <p>
+      Hurry, these offers won't last long! Visit our website or your nearest
+      store to take advantage of these amazing deals.
+    </p>
+    <p>
+      Happy shopping!<br />
+      The Weekly Coupons Team
+    </p>
+    <p>
+      <a href="{{amazonSESUnsubscribeUrl}}">Unsubscribe</a>
+    </p>
+  </body>
+</html>
diff --git a/workflows/sesv2_weekly_mailer/coupon-newsletter.txt b/workflows/sesv2_weekly_mailer/coupon-newsletter.txt
@@ -0,0 +1,16 @@
+Weekly Coupons Newsletter
+
+Check out this week's hot deals and exclusive coupons!
+
+{{#each coupons}}
+- {{details}}
+{{/each}}
+
+Hurry, these offers won't last long! Visit our website or your nearest store to take advantage of these amazing deals.
+
+Happy shopping!
+The Weekly Coupons Team
+
+---
+
+Unsubscribe: {{amazonSESUnsubscribeUrl}}
diff --git a/workflows/sesv2_weekly_mailer/sample_coupons.json b/workflows/sesv2_weekly_mailer/sample_coupons.json
@@ -0,0 +1,22 @@
+{
+  "coupons": [
+    {
+      "details": "20% off on all electronics"
+    },
+    {
+      "details": "Buy one, get one free on books"
+    },
+    {
+      "details": "15% off on home appliances"
+    },
+    {
+      "details": "Free shipping on orders over $50"
+    },
+    {
+      "details": "25% off on outdoor gear"
+    },
+    {
+      "details": "10% off on groceries"
+    }
+  ]
+}
diff --git a/workflows/sesv2_weekly_mailer/welcome.html b/workflows/sesv2_weekly_mailer/welcome.html
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Welcome to the Weekly Coupons Newsletter</title>
+  </head>
+  <body>
+    <h1>Welcome to the Weekly Coupons Newsletter!</h1>
+    <p>
+      Thank you for subscribing to our weekly newsletter. Every week, you'll
+      receive a list of exciting coupons and deals from our partners.
+    </p>
+    <p>Stay tuned for your first newsletter, coming soon!</p>
+    <p>Best regards,<br />The Weekly Coupons Team</p>
+  </body>
+</html>
diff --git a/workflows/sesv2_weekly_mailer/welcome.txt b/workflows/sesv2_weekly_mailer/welcome.txt
@@ -0,0 +1,8 @@
+Welcome to the Weekly Coupons Newsletter!
+
+Thank you for subscribing to our weekly newsletter. Every week, you'll receive a list of exciting coupons and deals from our partners.
+
+Stay tuned for your first newsletter, coming soon!
+
+Best regards,
+The Weekly Coupons Team