Using list management

To create a contact list by using the AWS CLI

• At the command line, enter the following command:

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

  In the preceding command, replace CONTACT-LIST-JSON with the path to your JSON file for your CreateContactList request.

  An example CreateContactList input JSON file for the request is as follows:

  {
      "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"
       }
      ]
  }

To create a contact by using the AWS CLI

• At the command line, enter the following command:

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

  In the preceding command, replace CONTACT-JSON with the path to your JSON file for your CreateContact request.

  An example CreateContact input JSON file for the request is as follows:

  {
      "ContactListName": "ExampleContactListName",
      "EmailAddress": "example@amazon.com",
      "UnsubscribeAll": false,
      "TopicPreferences": [
          {
              "TopicName": "Sports",
              "SubscriptionStatus": "OPT_IN"
          }
      ],
      "AttributesData": "{\"Name\": \"John\", \"Location\": \"Seattle\"}"
  }

  In the example above, an UnsubscribeAll value of false shows that the contact has not unsubscribed from all topics, where a value of true would mean the contact has unsubscribed from all topics.

  TopicPreferences includes information about the contact’s subscription status to topics. In the preceding example, the contact has opted in to the "Sports" topic and will receive all emails to the "Sports" topic.

  The AttributesData is a JSON field where you can put any metadata about our contact. It must be a valid JSON object.

1. List contacts by using the AWS CLI – You can use the ListContacts operation to retrieve a list of all your contacts who have subscribed to a particular topic, in conjunction with the SendEmail operation, which allows you to send them emails.

   At the command line, enter the following command:

   aws sesv2 list-contacts --cli-input-json file://LIST-CONTACTS-JSON

   In the preceding command, replace LIST-CONTACTS-JSON with the path to your JSON file for your ListContacts request.

   An example ListContacts input JSON file for the request is as follows:

   {
       "ContactListName": "ExampleContactListName",
       "Filter": {
           "FilteredStatus": "OPT_IN",
           "TopicFilter": {
               "TopicName": "Cycling",
               "UseDefaultIfPreferenceUnavailable": true
           }
       },
       "PageSize": 50
   }

   The FilteredStatus shows the subscription status for which you want to filter, which is either OPT_IN or OPT_OUT.

   The TopicFilter is an optional filter which specifies which topic you want results for, and in the example above, that is "Cycling."

   UseDefaultIfPreferenceUnavailable can have a value of true or false. If true, the topic default preference will be used if the contact doesn’t have any explicit preference for a topic. If false, only contacts with an explicitly set preference are considered for filtering.

2. Send mail with ListManagementOptions enabled – After listing the contacts in your list using the above ListContacts operation, you can use the SendEmail operation to send emails to each of your contacts by utilizing the ListManagementOptions header to specify your contact list and topic name.

   To use ListManagementOptions with the SendEmail operation, include the contactListName and topicName to which the email belongs (the topicName is optional):

   
   ListManagementOptions:
       String contactListName
       String topicName
                   

   If you include ListManagementOptions in your SendEmail request to a recipient email address that is not on your contact list, then a contact will be created on your list automatically.

   SES will issue a bounce event for a message that is sent to an unsubscribed contact on your contact list, which means you won’t need to update your SendEmail requests to avoid sending to contacts who have unsubscribed.

3. Indicate the location for your unsubscribe links – When utilizing ListManagementOptions you have the option to enable SES to add unsubscribe footer links in your email using the {{amazonSESUnsubscribeUrl}} placeholder to specify where SES needs to insert the unsubscribe URL. Placeholder replacement is supported only for HTML and TEXT content types. You can include the placeholder two times maximum. If used more than two times, only the first two occurrences are replaced. For more information, see Using subscription management.

   Alternatively, if you're using the SMTP interface to send email, you can use the X-SES-LIST-MANAGEMENT-OPTIONS header to specify a list and topic name.

   To specify a list and topic name while sending email using the SMTP interface, add the following email header to your message:

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