@dbos-inc/communicator-email-ses
v1.28.6
Published
DBOS library - email in AWS with SES
Downloads
1,111
Readme
DBOS AWS Simple Email Service (SES) Library
This is a DBOS communicator for sending email using the Amazon Web Services Simple Email Service.
Getting Started
In order to send emails with SES, it is necessary to:
- Register with AWS and create access keys for SES. (See Setting up SES in AWS documentation.)
- Verify a sending domain and destination addresses. (SES will initially be in "sandbox mode", which constrains email sending to be from a validated domain, to a validated email address. See Verified identities in AWS documentation.)
Configuring a DBOS Application with AWS SES
First, ensure that the DBOS SES communicator is installed into the application:
npm install --save @dbos-inc/communicator-email-ses
Second, ensure that the communicator is imported into the relevant source file(s):
import { SendEmailCommunicator } from "@dbos-inc/communicator-email-ses";
Third, place appropriate configuration into the dbos-config.yaml
file; the following example will pull the AWS information from the environment:
application:
aws_ses_configuration: aws_config # Optional if the section is called `aws_config`
aws_config:
aws_region: ${AWS_REGION}
aws_access_key_id: ${AWS_ACCESS_KEY_ID}
aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
If a different configuration file section should be used for SES, the aws_ses_configuration
can be changed to indicate a configuration section for use with SES. If multiple configurations are to be used, the application code will have to name and configure them.
For more information about configuring AWS services, see AWS Configuration.
Selecting A Configuration
SendEmailCommunicator
is a configured class. This means that the configuration (or config file key name) must be provided when a class instance is created. One instance per configuration should be created with configureInstance
when the application code starts. For example:
import { configureInstance } from "@dbos-inc/dbos-sdk";
// This will use the dbos-config.yaml section named by `aws_ses_configuration` if it is specified, or `aws_config` if not
const defaultSES = configureInstance(SendEmailCommunicator, 'default');
// This will use the section named `aws_config_marketing`
const marketingSES = configureInstance(SendEmailCommunicator, 'marketing', {awscfgname: 'aws_config_marketing'});
Sending Messages
Within a DBOS Transact Workflow, invoke the SendEmailCommunicator
function from the workflow context:
const result = await workflowContext.invoke(defaultSES).sendEmail(
{
to: [workflowContext.getConfig('ses_to_address', '[email protected]')],
from: workflowContext.getConfig('ses_from_address', '[email protected]'),
subject: 'Test email from DBOS',
bodyText: 'Check mailbox to see if it worked.'
}
);
Sending Templated Messages
Sending a templated email is slightly more involved, as a template must be set up first. Setting up a template can be invoked as a communicator, or directly (so that it can be called from initialization, or other contexts where a workflow may not be in progress).
- Use
workflowContext.invoke(defaultSES).createEmailTemplate(...)
or `SendEmailCommunicator.createEmailTemplateFunction(...) to create the template.
await workflowContext.invokeOnConfg(defaultSES).createEmailTemplate(
"testTemplate", {subject: "Email using test template", bodyText: "Today's date is {{todaydate}}."}
);
- Within a workflow, send email with the template, noting that the template substitution data is to be stringified JSON:
await workflowContext.invoke(defaultSES).sendTemplatedEmail({
to: [workflowContext.getConfig('ses_to_address', '[email protected]')],
from: workflowContext.getConfig('ses_from_address', '[email protected]'),
templateName: "testTemplate",
templateDataJSON: JSON.stringify({todaydate: new Date().toISOString()}),
});
Simple Testing
The ses.test.ts
file included in the source repository can be used to send an email and a templated email. Before running, set the following environment variables:
SES_FROM_ADDRESS
: An email address within a verified SES sending domainSES_TO_ADDRESS
: Destination email address (which must first be verified with SES if in sandbox mode)AWS_REGION
: AWS region to useAWS_ACCESS_KEY_ID
: The access key with permission to use the SES serviceAWS_SECRET_ACCESS_KEY
: The secret access key corresponding toAWS_ACCESS_KEY_ID
Notes
While some email services allow setting of a Message-ID
, which would form the foundation of an idempotent email send, SES does not. This communicator may send duplicate emails in the case of a poorly-timed network or server failure.
Next Steps
- For a detailed DBOS Transact tutorial, check out our programming quickstart.
- To learn how to deploy your application to DBOS Cloud, visit our cloud quickstart
- To learn more about DBOS, take a look at our documentation or our source code.