This is a DBOS step for sending email using the Amazon Web Services Simple Email Service.

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.)

First, ensure that the DBOS SES installed into the application:

npm install --save @dbos-inc/dbos-email-ses

Second, ensure that the library is imported into the relevant source file(s):

import { DBOS_SES } from "@dbos-inc/dbos-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.

DBOS_SES 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 DBOS.configureInstance when the application code starts. For example:

import { DBOS } 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 = DBOS.configureInstance(DBOS_SES, 'default');
// This will use the section named `aws_config_marketing`
const marketingSES = DBOS.configureInstance(DBOS_SES, 'marketing', {awscfgname: 'aws_config_marketing'});

Within a DBOS Transact Workflow, call DBOS_SES functions:

    const result = await 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 a templated email is slightly more involved, as a template must be set up first. Setting up a template can be invoked as a DBOS step, or directly (so that it can be called from initialization, or other contexts where a workflow may not be in progress).

• Use defaultSES.createEmailTemplate(...) or DBOS_SES.createEmailTemplateFunction(...) to create the template.

    await 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 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()}),
    });

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 domain
• SES_TO_ADDRESS: Destination email address (which must first be verified with SES if in sandbox mode)
• AWS_REGION: AWS region to use
• AWS_ACCESS_KEY_ID: The access key with permission to use the SES service
• AWS_SECRET_ACCESS_KEY: The secret access key corresponding to AWS_ACCESS_KEY_ID

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.

• To start a DBOS app from a template, visit our quickstart.
• For DBOS Transact programming tutorials, check out our programming guide.
• To learn more about DBOS, take a look at our documentation or our source code.