AWS Step Functions: Sending an Email from a State

In today's agile and always-connected world, automation and workflow orchestration are crucial for operational efficiency. AWS Step Functions is a service that simplifies the coordination of distributed application components and microservices using visual workflows. One of the most powerful features of Step Functions is its direct integration with various AWS services through AWS SDK. This functionality allows developers to quickly build complex applications with less code and maintenance. In this post, we will explore how this integration works, specifically focusing on how to send emails using Amazon Simple Email Service (SES) V2.

What is and How Does an AWS SDK Integration from Step Function Work?

The integration of AWS SDK into Step Functions allows users to make direct calls to AWS services without the need for writing a custom Lambda function for the interaction. This means you can use AWS APIs directly within your Step Functions state machine definition.

When you configure a state in your state machine to perform an AWS SDK operation, you simply specify the AWS service and the action you wish to use, along with the necessary parameters for that API call. Step Functions handles the API request and response, including retry attempts and error handling.

Official documentation for this:

• AWS SDK Services Support
• Connect to a Resource Example

Common Use Cases for This Type of Integration

• Data Processing: Execute tasks such as data transformations and analytics using services like AWS Glue or Amazon EMR.
• Infrastructure Automation: Orchestrate changes in AWS infrastructure, such as updating AWS CloudFormation stacks or launching Amazon EC2 instances.
• Application Integrations: Communicate with other AWS services to send notifications with Amazon SNS, message queues with Amazon SQS, or store files in Amazon S3.
• User Management: Automate the creation and management of users in AWS Identity and Access Management (IAM).

Example: Sending an Email with SES V2

Imagine that you need to send confirmation emails to users after they complete an action in your application. Instead of invoking a Lambda function that in turn calls SES, you can use Step Functions to call SES directly.

Here is an example of how to send an email using arn:aws:states:::aws-sdk:sesv2:sendEmail:

{
  "StartAt": "SendEmail",
  "States": {
    "SendEmail": {
      "Type": "Task",
      "Resource": "arn:aws:states:::aws-sdk:sesv2:sendEmail",
      "Parameters": {
        "FromEmailAddress": "sender@example.com",
        "Destination": {
          "ToAddresses": ["recipient@example.com"]
        },
        "Content": {
          "Simple": {
            "Subject": {
              "Data": "Your confirmation email",
              "Charset": "UTF-8"
            },
            "Body": {
              "Text": {
                "Data": "Thank you for your action.",
                "Charset": "UTF-8"
              }
            }
          }
        }
      },
      "End": true
    }
  }
}

In this SendEmail state, we have defined a task that utilizes the resource arn:aws:states:::aws-sdk:sesv2:sendEmail. The Parameters specify the sender's email, the recipient, and the content of the email, including both the subject and the body.

This approach simplifies the architecture of your application, as there is no need to code and maintain a Lambda function for tasks that can be handled directly by Step Functions. Furthermore, error handling and retry mechanisms can be managed within the state machine's definition, providing a robust and reliable solution.

How Can You Find the Parameters for a Specific Integration?

1. On this page https://docs.aws.amazon.com/step-functions/latest/dg/supported-services-awssdk.html, you will find the enabled integrations for multiple AWS services.
2. Then, search for the API documentation of the integration you are going to use. In this example, SES V2 was used, so we would search at https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html.
3. On the reference page, look for the action you want to perform, in this case, SendEmail.
4. At this point, we will see the syntax of the request, details such as the URL, headers, and body of the request. Our focus will be on the body of the request:

POST /v2/email/outbound-emails HTTP/1.1
Content-type: application/json

{
   "Content": {
      "Simple": {
      "Body": {
         "Text": {
            "Charset": "UTF-8",
            "Data": "body"
         }
      },
      "Subject": {
         "Charset": "UTF-8",
         "Data": "subject"
      }
      }
   },
   "Destination": {
      "ToAddresses": [
      "email"
      ]
   },
   "FromEmailAddress": "email"
}

1. These same parameters that we see in the body are what we are going to add in the state definition of our state function.

In summary, the direct integration of AWS SDK into Step Functions opens a world of possibilities for orchestrating AWS services efficiently and effectively, allowing developers to focus on business logic rather than service integration.
In this repository https://github.com/jjoc007/poc_step_functions_examples/tree/main/2_send_email_via_ses, you will see the example ready to deploy with Terraform, feel free to download it and try it out.

If you liked this article, don't hesitate to give it a 👏 and a ⭐ on the repository.

Thank you.

Links:

• Spanish version
• AWS Step Functions: Using the Wait State Type
• Introduction to AWS Step Functions Using Terraform as Infrastructure-as-Code Tool