Tag Archives: Messaging and Targeting

How quirion created nested email templates using Amazon Simple Email Service (SES)

Post Syndicated from Dominik Richter original https://aws.amazon.com/blogs/messaging-and-targeting/how-quirion-created-nested-email-templates-using-amazon-simple-email-service-ses/

This is part two of the two-part guest series on extending Simple Email Services with advanced functionality. Find part one here.

quirion, founded in 2013, is an award-winning German robo-advisor with more than 1 billion Euro under management. At quirion, we send out five thousand emails a day to more than 60,000 customers.

Managing many email templates can be challenging

We chose Amazon Simple Email Service (SES) because it is an easy-to-use and cost-effective email platform. In particular, we benefit from email templates in SES, which ensure a consistent look and feel of our communication. These templates come with a styled and personalized HTML email body, perfect for transactional emails. However, managing many email templates can be challenging. Several templates share common elements, such as the company’s logo, name or imprint. Over time, some of these elements may change. If they are not updated across all templates, the result is an inconsistent set of templates. To overcome this problem, we created an application to extend the SES template functionality with an interface for creating and managing nested templates.

This post shows how you can implement this solution using Amazon Simple Storage Service (Amazon S3), Amazon API Gateway, AWS Lambda and Amazon DynamoDB.

Solution: compose email from nested templates using AWS Lambda

The solution we built is fully serverless, which means we do not have to manage the underlying infrastructure. We use AWS Cloud Development Kit (AWS CDK) to deploy the architecture.

The figure below describes the architecture diagram for the proposed solution.

  1. The entry point to the application is an API Gateway that routes requests to a Lambda function. A request consists of an HTML file that represents a part of an email template and metadata that describes the structure of the template.
  2. The Lambda function is the key component of the application. It takes the HTML file and the metadata and stores them in a S3 Bucket and a DynamoDB table.
  3. Depending on the metadata, it takes an existing template from storage, inserts the HTML from the request into it and creates a SES email template.

Architecture diagram of the solution: new templates in Amazon SES are created by a Lambda function accessed through API Gateway. THe Lambda function reads and writes HTML from S3 and reads and writes metadata from DynamoDB.

The solution is simplified for this blog post and is used to show the possibilities of SES. We will not discuss the code of the Lambda function as there are several ways to implement it depending on your preferred programming language.

Prerequisites

Walkthrough

Step 1: Use the AWS CDK to deploy the application
To download and deploy the application run the following commands:

$ git clone https://github.com/quirionit/aws-ses-examples.git
$ cd aws-ses-examples/projects/go-src
$ go mod tidy
$ cd ../../projects/template-api
$ npm install
$ cdk deploy

Step 2: Create nested email templates

To create a nested email template, complete the following steps:

  1. On the AWS Console, choose the API Gateway.
  2. You should see an API with a name that includes SesTemplateApi.
    Console screenshot displaying the SesTemplateApi
  3. Click on the name and note the Invoke URL from the details page.

    AWS console showing the invoke URL of the API

  4. In your terminal, navigate to aws-ses-examples/projects/template-api/files and run the following command. Note that you must use your gateway’s Invoke URL.
    curl -F [email protected] -F "isWrapper=true" -F "templateName=m-full" -F "child=content" -F "variables=FIRSTNAME" -F "variables=LASTNAME" -F "plain=Hello {{.FIRSTNAME}} {{.LASTNAME}},{{template \"content\" .}}" YOUR INVOKE URL/emails

    The request triggers the Lambda function, which creates a template in DynamoDB and S3. In addition, the Lambda function uses the properties of the request to decide when and how to create a template in SES. With “isWrapper=true” the template is marked as a template that wraps another template and therefore no template is created in SES. “child=content” specifies the entry point for the child template that is used within m-full.html. It also uses FIRSTNAME and LASTNAME as replacement tags for personalization.

  5. In your terminal, run the following command to create a SES email template that uses the template created in step 4 as a wrapper.

Step 3: Analyze the result

  1. On the AWS Console, choose DynamoDB.
  2. From the sidebar, choose Tables.
  3. Select the table with the name that includes SesTemplateTable.
  4. Choose Explore table items. It should now return two new items.
    Screenshot of the DynamoDB console, displaying two items: m-full and order-confirmation.
    The table stores the metadata that describes how to create a SES email template. Creating an email template in SES is initiated when an element’s Child attribute is empty or null. This is the case for the item with the name order-confirmation. It uses the BucketKey attribute to identify the required HTML stored in S3 and the Parent attribute to determine the metadata from the parent template. The Variables attribute is used to describe the placeholders that are used in the template.
  5. On the AWS Console, choose S3.
  6. Select the bucket with the name that starts with ses-email-templates.
  7. Select the template/ folder. It should return two objects.
    Screenshot of the S3 console, displaying two items: m-full and order-confirmation.
    The m-full.html contains the structure and the design of an email template and is used with the order-confirmation.html which contains the content.
  8. On the AWS Console, choose the Amazon Simple Email Service.
  9. From the sidebar, choose Email templates. It should return the following template.
    Screenshot of the SES console, displaying the order confirmation template

Step 4: Send an email with the created template

  1. Open the send-order-confirmation.json file from aws-ses-examples/projects/template-api/files in a text editor.
  2. Set a verified email address as Source and ToAddresses and save the file.
  3. Navigate your terminal to aws-ses-examples/projects/template-api/files and run the following command:
    aws ses send-templated-email --cli-input-json file://send-order-confirmation.json
  4. As a result, you should get an email.

Step 5: Cleaning up

  1. Navigate your terminal to aws-ses-examples/projects/template-api.
  2. Delete all resources with cdk destroy.
  3. Delete the created SES email template with:
    aws ses delete-template --template-name order-confirmation

Next Steps

There are several ways to extend this solution’s functionality, including the ones below:

  • If you send an email that contains invalid personalization content, Amazon SES might accept the message, but won’t be able to deliver it. For this reason, if you plan to send personalized email, you should configure Amazon SES to send Rendering Failure event notifications.
  • The Amazon SES template feature does not support sending attachments, but you can add the functionality yourself. See part one of this blog series for instructions.
  • When you create a new Amazon SES account, by default your emails are sent from IP addresses that are shared with other SES users. You can also use dedicated IP addresses that are reserved for your exclusive use. This gives you complete control over your sender reputation and enables you to isolate your reputation for different segments within email programs.

Conclusion

In this blog post, we explored how to use Amazon SES with email templates to easily create complex transactional emails. The AWS CLI was used to trigger SES to send an email, but that could easily be replaced by other AWS services like Step Functions. This solution as a whole is a fully serverless architecture where we don’t have to manage the underlying infrastructure. We used the AWS CDK to deploy a predefined architecture and analyzed the deployed resources.

About the authors

Mark Kirchner is a backend engineer at quirion AG. He uses AWS CDK and several AWS services to provide a cloud backend for a web application used for financial services. He follows a full serverless approach and enjoys resolving problems with AWS.
Dominik Richter is a Solutions Architect at Amazon Web Services. He primarily works with financial services customers in Germany and particularly enjoys Serverless technology, which he also uses for his own mobile apps.

The content and opinions in this post are those of the third-party author and AWS is not responsible for the content or accuracy of this post.

How quirion sends attachments using email templates with Amazon Simple Email Service (SES)

Post Syndicated from Dominik Richter original https://aws.amazon.com/blogs/messaging-and-targeting/how-quirion-sends-attachments-using-email-templates-with-amazon-simple-email-service-ses/

This is part one of the two-part guest series on extending Simple Email Services with advanced functionality. Find part two here.

quirion is an award-winning German robo-advisor, founded in 2013, and with more than 1 billion euros under management. At quirion, we send out five thousand emails a day to more than 60,000 customers.

We chose Amazon Simple Email Service (SES) because it is an easy-to-use and cost-effective email platform. In particular, we benefit from email templates in SES, which ensure a consistent look and feel of our communication. These templates come with a styled and personalized HTML email body, perfect for transactional emails. Sometimes it is necessary to add attachments to an email, which is currently not supported by the SES template feature. To overcome this problem, we created a solution to use the SES template functionality and add file attachments.

This post shows how you can implement this solution using Amazon Simple Storage Service (Amazon S3), Amazon EventBridge, AWS Lambda and AWS Step Functions.

Solution: orchestrate different email sending options using AWS Step Functions

The solution we built is fully serverless, which means we do not have to manage the underlying infrastructure. We use AWS Cloud Development Kit (AWS CDK) to deploy the architecture and analyze the resources.

The solution extends SES to send attachments using email templates. SES offers three possibilities for sending emails:

  • Simple  — A standard email message. When you create this type of message, you specify the sender, the recipient, and the message body, and Amazon SES assembles the message for you.
  • Raw — A raw, MIME-formatted email message. When you send this type of email, you have to specify all of the message headers, as well as the message body. You can use this message type to send messages that contain attachments. The message that you specify has to be a valid MIME message.
  • Templated — A message that contains personalization tags. When you send this type of email, Amazon SES API v2 automatically replaces the tags with values that you specify.

In this post, we will combine the Raw and the Templated options.

The figure below describes the architecture diagram for the proposed solution.

  1. The entry point to the application is an EventBridge event bus that routes incoming events to a Step Function workflow.
  2. An event consists of the personalization parameters, the sender and recipient addresses, the template name and optionally the document-related properties such as a reference to the S3 bucket in which the document is stored. Depending on whether the event contains document-related properties, the Step Function workflow decides how the email is prepared and sent.
  3. In case the event does not contain document-related properties, it uses the SendEmail action to send a templated email. The action requires the template name and the data to replace the personalization tags.
  4. If the event contains document-related properties, the raw sending option of the SendEmail action must be used. If we also want to use an email template, we need to use that as a raw MIME message. So, we use the TestRenderEmailTemplate action to get the raw MIME message from the template and use a Lambda function to get and add the document. The Lambda function then triggers SES to send the email.

The solution is simplified for this blog post and is used to show the possibilities of SES. We will not discuss the code of the lambda function as there are several ways to implement it depending on your preferred programming language.

Architecture diagram of the solution: an AWS Step Functions workflow is triggered by EventBridge. If the event contains no document, the workflow triggers Amazon SES SendEmail. Otherwise, it uses SES TestRenderEmailTemplate as input for a Lambda function, which gets the document from S3 and then sends the email.

Prerequisites

Walkthrough

Step 1: Use the AWS CDK to deploy the application

To download and deploy the application run the following commands:

$ git clone [email protected]:quirionit/aws-ses-examples.git
$ cd aws-ses-examples/projects/go-src
$ go mod tidy
$ cd ../../projects/email-sender
$ npm install
$ cdk deploy

Step 2: Create a SES email template

In your terminal, navigate to aws-ses-examples/projects/email-sender and run:

aws ses create-template --cli-input-json file://files/hello_doc.json

Step 3: Upload a sample document to S3

To upload a document to S3, complete the following steps:

  1. On the AWS Console, choose the S3.
  2. Select the bucket with the name that starts with ses-documents.
  3. Copy and save the bucket name for later.
  4. Create a new folder called test.
  5. Upload the hello.txt from aws-ses-examples/projects/email-sender/files into the folder.

Screenshot of Amazon S3 console, showing the ses-documents bucket containing the file tes/hello.txt

Step 4: Trigger sending an email using Amazon EventBridge

To trigger sending an email, complete the following steps:

  1. On the AWS Console, choose the Amazon EventBridge.
  2. Select Event busses from the sidebar.
  3. Select Send events.
  4. Create an event as the following image shows. You can copy the Event detail from aws-ses-examples/projects/email-sender/files/event.json. Don’t forget to replace the sender, recipient and bucket with your values.
    Screenshot of EventBridge console, showing how the sample event with attachment is sent.
  5. As a result of sending the event, you should receive an email with the document attached.
  6. To send an email without attachment, edit the event as follows:
    Screenshot of EventBridge console, showing how the sample event without attachment is sent.

Step 5: Analyze the result

  1. On the AWS Console, choose Step Functions.
  2. Select the state machine with the name that includes EmailSender.
  3. You should see two Succeeded executions. If you select them the dataflows should look like this:
    Screenshot of Step Functions console, showing the two successful invocations.
  4. You can select each step of the dataflows and analyze the inputs and outputs.

Step 6: Cleaning up

  1. Navigate your terminal to aws-ses-examples/projects/email-sender.
  2. Delete all resources with cdk destroy.
  3. Delete the created SES email template with:

aws ses delete-template --template-name HelloDocument

Next Steps

There are several ways to extend this solution’s functionality, see some of them below:

  • If you send an email that contains invalid personalization content, Amazon SES might accept the message, but won’t be able to deliver it. For this reason, if you plan to send personalized email, you should configure Amazon SES to send Rendering Failure event notifications.
  • You can create nested templates to share common elements, such as the company’s logo, name or imprint. See part two of this blog series for instructions.
  • When you create a new Amazon SES account, by default your emails are sent from IP addresses that are shared with other SES users. You can also use dedicated IP addresses that are reserved for your exclusive use. This gives you complete control over your sender reputation and enables you to isolate your reputation for different segments within email programs.

Conclusion

In this blog post, we explored how to use Amazon SES to send attachments using email templates. We used an Amazon EventBridge to trigger a Step Function that chooses between sending a raw or templated SES email. This solution uses a full serverless architecture without having to manage the underlying infrastructure. We used the AWS CDK to deploy a predefined architecture and analyzed the deployed resources.

About the authors

Mark Kirchner is a backend engineer at quirion AG. He uses AWS CDK and several AWS services to provide a cloud backend for a web application used for financial services. He follows a full serverless approach and enjoys resolving problems with AWS.
Dominik Richter is a Solutions Architect at Amazon Web Services. He primarily works with financial services customers in Germany and particularly enjoys Serverless technology, which he also uses for his own mobile apps.

The content and opinions in this post are those of the third-party author and AWS is not responsible for the content or accuracy of this post.

Send SMS at scale to Indian recipients using Amazon Pinpoint

Post Syndicated from Meng Kang original https://aws.amazon.com/blogs/messaging-and-targeting/send-sms-at-scale-to-indian-recipients-using-amazon-pinpoint/

SMS has one of the highest open rates of all customer communications channels, and is popular with application builders for both transactional use cases like appointment reminders or asynchronous use cases like a SMS chatbot. Amazon Pinpoint supports SMS in over 200 countries and territories, but SMS sending requirements can vary by recipient destination. SMS sending requirements, depending on locale, can include restrictions on origination identity used, messages content, or the routes used to deliver to recipients. Amazon Pinpoint is making it easier for you to send application-to-person (A2P) SMS to Indian recipients using domestic routes. Amazon Pinpoint now supports submitting the Principal Entity ID (PEID) and Template ID using the Send Message API.

Introduction to new regulations and DLT platform

In 2018, the Telecom Regulatory Authority of India (TRAI) released The Telecom Commercial Communication Customer Preference Regulation (TCCCPR) to regulate text messaging in India. To implement this, TRAI adopted a block-chain technology called the Distributed Ledger Technology (DLT) platform. Every business entity who wants to send Application-to-Person (A2P) SMS to their end users in India using domestic routes will need to register their business and use case on the DLT platform. DLT registration is a concept that is unique to the SMS industry in India. If you don’t send text messages to recipients in India then DLT registration doesn’t apply to you. You will not be able to send A2P SMS to Indian recipients using domestic routes if you do not register on the DLT platform. Please note that if you are an international enterprise and you would like to send A2P SMS to recipients in India, you can leverage Amazon Pinpoint’s International Long Distance Operator (ILDO) routes. See more information here.

Changes in sending A2P SMS

DLT has brought many changes to the way SMS is sent in India. These include a new registration process, new message categorization, as well as restrictions around how to send messages. See below for an overview of this process.

Registration with TRAI: Prior to DLT, only service providers/telemarketers were required to register with TRAI. With the updated regulations, business owners/principal entity who wants to send SMS to their customers in India have to sign-up and complete the registration process on DLT platform.

Sender ID & Template Registration: Prior to DLT, bulk SMS service providers used to approve Sender IDs and templates. With the updated regulations, business owners/principal entity have to register Sender ID and Templates on the DLT platform and get those approved.

Customer Preference and Consent: Prior to DLT, customers were either on National Do Not Disturb Registry (DND) or not. The new regulation gave control to consumers/mobile subscribers by offering a time-window where they can manage their preferences based on a specific time or day and allow receipt of certain kinds of promotional messages. It means that customers can choose to receive promotional text from a company even if they have activated DND.

Types of Message: With the new regulation, the DLT-defined domestic routes are as follows.

  • Promotional SMS: these include offers, discounts to non-opt in users, and SMS delivered to Non-DND numbers where the customer has not explicitly opted in. These can only be delivered between 10.00AM to 21:00PM IST. Operators have also stopped supporting delivery notification and receipts for promotional SMS. Promotional messages are sent using 6-digit numeric Sender IDs.
  • Transactional SMS: this is reserved for financial organizations to send One-Time-Passwords (OTPs). Transactional messages use 6-digit alpha Sender IDs.
  • Service Implicit: these include service-related informative messages other than OTPs. Amazon Pinpoint classifies these under the “transactional” route type, so customers will continue to select the “transactional” route type to send these messages.
  • Service Explicit: these include promotional messages customers have opted to receive from a particular business. Amazon Pinpoint classifies these under the “transactional” route type, so customers will continue to select the “transactional” route type to send these messages.

Validation (Scrubbing) Functionality: With DLT, customers’ mobile numbers are filtered in real-time to match the desired criteria set by the customer. This means that if a customer gave consent to receive SMS on Monday, but withdraws the permission on Wednesday, then the SMS will not be delivered on Thursday. Customer preferences are updated in real-time and the results are immediately available on DLT. When sending, the DLT platform will validate the PEID customers used to send against the registered Sender ID, and validate the SMS Template against the registered Brand name, so that only approved businesses using approved SMS Sender are able to send SMS to the end recipient.

DLT registration timeline

TRAI is the entity enforcing DLT implementation in India. TRAI has designated these changes to take place over several phases and months, with each phase increasing the level of restriction on message sending:

Phase 1 (Initiated June 2020): The first phase is to complete Principal Entity ID (PEID) & the SMS Header or Sender ID registration on the DLT platform. Only registered SMS Header or Sender ID can be used to send SMS to India using domestic routes.

Phase 2 (Initiated Nov 2020): The second phase is to register Template ID on the DLT platform. For each SMS send, the PEID and Template ID are validated against the registered Sender ID.

Phase 3 (Initiated April 2021): The third phase is to validate that the content of the message template matches exactly what was registered on the DLT platform. Brand Name is a mandatory field to be included in content for template registration.

Using Pinpoint to send SMS to India

To send SMS messages to India from Amazon Pinpoint, you’ll first need to complete DLT registration. To do so, follow the steps described on the Special requirements for sending SMS messages to recipients in India documentation.

Next, to make sure your SMS messages are delivered successfully using local routes, you need to do the following when using Amazon Pinpoint sending the SMS message.

  • Use a Sender ID which has been registered on the DLT platform that matches your message content.
  • In the Pinpoint Send Message API, provide values for the following parameters:
    • EntityId – The entity ID or Principal Entity (PE) ID received from the regulatory body for sending SMS in your country.
    • TemplateId – The template ID received from the regulatory body for sending SMS in your country.
  • Choose one of the following route types:
    • Promotional – Choose this type for promotional messages, which use a numeric sender ID.
    • Transactional – Choose this type for transactional messages, which use a case-sensitive alphanumeric sender ID.

When adding the content to your message, thoroughly review your content to ensure that it exactly matches the content in the DLT registered template. If you include additional character returns, spaces, punctuation, or mismatched sentence case, carriers will block your SMS. Variables in a template – for example, {#var#} – cannot exceed 30 characters for each variable. The following are some common use cases for message rejection:

No template was found that matched the content sent.
Content sent: <#> 12345 is your OTP to verify mobile number. Your OTP is valid for 15 minutes — ABC Pvt. Ltd.
Matched template: None
Issue: There are no DLT templates that include <#> or {#var#} at the beginning of the DLT registered template.

The value of a variable exceeds 30 characters.
Content sent: 12345 is your OTP code for ABC (ABC Company – India Private Limited) – (ABC 123456789). Share with your agent only. – ABC Pvt. Ltd.
Matched template: {#var#} is your OTP code for {#var#} ({#var#}) – ({#var#} {#var#}). Share with your agent only. – ABC Pvt. Ltd.
Issue: The value of “ABC Company – India Private Limited” in the content sent exceeds a single {#var#} character limit of 30.

The message sentence case does not match the sentence case in the template.
Content sent: 12345 is your OTP code for ABC (ABC Company – India Private Limited) – (ABC 123456789). Share with your agent only. – ABC Pvt. Ltd.
Matched template: {#var#} is your OTP code for {#var#} ({#var#}) – ({#var#} {#var#}). Share with your agent only. – ABC PVT. LTD.
Issue: The company name appended to the DLT matched template is capitalized while the content sent has changed parts of the name to lowercase — “ABC Pvt. Ltd.” vs. “ABC PVT. LTD.”

Start using Amazon Pinpoint to send SMS messages to Indian recipients by following the steps described on the Special requirements for sending SMS messages to recipients in India documentation.