npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@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 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

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