EmailProvidersAWS SES

AWS SES

Send emails using Amazon Simple Email Service with @visulima/email

AWS SES Provider

The AWS SES provider allows you to send emails through Amazon Simple Email Service using native Node.js APIs with AWS Signature V4 signing. No AWS SDK dependency is required.

Runtime Support: Node.js only (requires node:crypto for AWS Signature V4 signing)

Setup

import { createMail } from "@visulima/email";
import { awsSesProvider } from "@visulima/email/providers/aws-ses";

const mail = createMail(
    awsSesProvider({
        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
        region: "us-east-1",
    }),
);

Configuration

The AwsSesConfig interface extends BaseConfig with the following options:

OptionTypeRequiredDefaultDescription
accessKeyIdstringYes-AWS access key ID
secretAccessKeystringYes-AWS secret access key
regionstringYesus-east-1AWS region
sessionTokenstringNo-AWS session token (for temporary credentials)
apiVersionstringNo2010-12-01AWS SES API version
endpointstringNoAuto-resolvedCustom endpoint (defaults to email.{region}.amazonaws.com)
maxAttemptsnumberNo3Maximum request attempts
debugbooleanNofalseEnable debug logging
loggerConsoleNo-Custom logger instance

Basic Usage

import { MailMessage } from "@visulima/email";

const message = new MailMessage()
    .to("user@example.com")
    .from("sender@example.com")
    .subject("Hello from AWS SES")
    .html("<h1>Hello World</h1>");

const result = await mail.send(message);

Provider-Specific Email Options

The AWS SES provider supports additional options through AwsSesEmailOptions:

import type { AwsSesEmailOptions } from "@visulima/email/providers/aws-ses";

const options: AwsSesEmailOptions = {
    from: { email: "sender@example.com" },
    to: { email: "user@example.com" },
    subject: "Hello",
    html: "<h1>Hello</h1>",
    configurationSetName: "my-config-set",
    messageTags: {
        Environment: "production",
        Application: "my-app",
    },
    sourceArn: "arn:aws:ses:us-east-1:123456789:identity/example.com",
    returnPath: "bounce@example.com",
    returnPathArn: "arn:aws:ses:us-east-1:123456789:identity/example.com",
};
OptionTypeDescription
configurationSetNamestringConfiguration set name
messageTagsRecord<string, string>Message tags as key-value pairs
sourceArnstringSource ARN for sending authorization
returnPathstringReturn path email address
returnPathArnstringReturn path ARN

Supported Features

FeatureSupported
AttachmentsNo
Batch SendingNo
Custom HeadersYes
HTMLYes
Reply-ToNo
SchedulingNo
TaggingNo
TemplatesNo
TrackingNo

Important Notes

  • This provider uses the SendRawEmail API action, which generates a full MIME message internally.
  • Unsupported fields (attachments, priority, tags, replyTo) will cause an error if provided, rather than being silently ignored.
  • The provider uses native node:crypto for AWS Signature V4 signing and does not require the AWS SDK.
Support

Contribute to our work and keep us going

Community is the heart of open source. The success of our packages wouldn't be possible without the incredible contributions of users, testers, and developers who collaborate with us every day.Want to get involved? Here are some tips on how you can make a meaningful impact on our open source projects.

Ready to help us out?

Be sure to check out the package's contribution guidelines first. They'll walk you through the process on how to properly submit an issue or pull request to our repositories.

Submit a pull request

Found something to improve? Fork the repo, make your changes, and open a PR. We review every contribution and provide feedback to help you get merged.

Good first issues

Simple issues suited for people new to open source development, and often a good place to start working on a package.
View good first issues