aws-ses-v2-local

A local version of Amazon Simple Email Service (AWS SES) supporting both the V1 API and the V2 API. Currently focuses on the SendEmail and SendRawEmail endpoints.

Are you using serverless-offline? You might be interested in serverless-offline-ses-v2.

| HTML emails | Dark theme | | - | - | | | |

Features

• SES V1 SendEmail endpoint
• SES V1 SendRawEmail endpoint
• SES V2 SendEmail endpoint (both Simple, Raw and Template)
• SES V2 sendBulkEmail endpoint
• SES V2 createEmailTemplate endpoint
• SES V2 getEmailTemplate endpoint
• SES V2 listEmailTemplates endpoint
• SES V2 updateEmailTemplate endpoint
• SES V2 deleteEmailTemplate endpoint
• SES V2 testRenderEmailTemplate endpoint (returns the rendered MIME message)
• SES V2 getAccount endpoint (returns the content of the AWS_SES_ACCOUNT env variable)
• Handlebars email templates (variables, {{#each}}, {{#if}}, dotted paths, and other built-in helpers), matching AWS SES's rendering — see Email templates
• Realistic API responses, compatible with the AWS SDK (in JavaScript/TypeScript/Node.js, Java, Python, Go, C++, .NET, PHP, Ruby) and the AWS CLI
• To, Cc, Bcc, ReplyTo and From addresses
• Plain text and HTML emails
• Accept and view attachments
• Built in web viewer, with live inbox, optional dark theme, and compatibility with all emails
• API access to emails at GET /store
• Health check endpoint at GET /health-check
• Control it from the CLI, or import it as a library
• TypeScript definitions
• Emails can be forwarded to a SMTP server via the SMTP_TRANSPORT env variable

Install

npm install aws-ses-v2-local

Usage

Setting up aws-ses-v2-local

Run it as a command line tool (in your package.json scripts, or install it globally with npm install -g aws-ses-v2-local)

aws-ses-v2-local

Alternatively, you can import it and run it yourself (along with optional config for the port):

import server from 'aws-ses-v2-local'

server({ port: 8005 })
console.log('aws-ses-v2-local: server up and running')

Setting up your application

You can treat the server as an AWS SES endpoint. See the starter for your language:

import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2"

const ses = new SESv2Client({
    endpoint: 'http://localhost:8005',
    region: 'aws-ses-v2-local',
    credentials: { accessKeyId: 'ANY_STRING', secretAccessKey: 'ANY_STRING' },
});
await ses.send(new SendEmailCommand({
    FromEmailAddress: '[email protected]',
    Destination: { ToAddresses: ['[email protected]'] },
    Content: {
        Simple: {
            Subject: { Data: 'This is the subject' },
            Body: { Text: { Data: 'This is the email contents' } },
        }
    },
}))

import { SES, SendEmailCommand } from '@aws-sdk/client-ses'

const ses = new SES({
    endpoint: 'http://localhost:8005',
    region: 'aws-ses-v2-local',
    credentials: { accessKeyId: 'ANY_STRING', secretAccessKey: 'ANY_STRING' },
})
await ses.send(new SendEmailCommand({
    Source: '[email protected]',
    Destination: { ToAddresses: ['[email protected]'] },
    Message: {
        Subject: { Data: 'This is the subject' },
        Body: { Text: { Data: 'This is the email contents' } },
    },
}))

import AWS from 'aws-sdk'

const ses = new AWS.SESV2({
    endpoint: 'http://localhost:8005',
    region: 'aws-ses-v2-local',
    credentials: { accessKeyId: 'ANY_STRING', secretAccessKey: 'ANY_STRING' },
})
ses.sendEmail({
    FromEmailAddress: '[email protected]',
    Destination: { ToAddresses: ['[email protected]'] },
    Content: {
        Simple: {
            Subject: { Data: 'This is the subject' },
            Body: { Text: { Data: 'This is the email contents' } },
        }
    },
})

import * as aws from '@aws-sdk/client-ses'

const ses = new aws.SES({
    endpoint: 'http://localhost:8005',
    region: 'aws-ses-v2-local',
    credentials: { accessKeyId: 'ANY_STRING', secretAccessKey: 'ANY_STRING' },
})
const transporter = nodemailer.createTransport({ SES: { ses, aws } })

await transporter.sendMail({
    from: '[email protected]',
    to: ['[email protected]'],
    subject: 'This is the subject',
    text: 'This is the email contents',
    attachments: [{
        filename: `some-file.pdf`,
        contentType: 'application/pdf',
        content: Buffer.from(pdfBytes),
    }],
})

Using another language or version? Submit a PR to update this list :)

Email templates

Templates created with createEmailTemplate are rendered with Handlebars, the same engine AWS SES uses. This supports variables ({{name}}), dotted paths ({{user.name}}), {{#each}}, {{#if}}/{{#unless}}, and the other built-in helpers. As on real SES, values are not HTML-escaped — escape untrusted input yourself before putting it in the template data.

sendBulkEmail merges each entry's ReplacementTemplateData into DefaultContent.TemplateData per key, matching real SES: replacement keys override the defaults (recursively for nested objects; arrays and scalar values are replaced wholesale), and keys the entry doesn't supply fall back to the default data. An empty ({}) or absent ReplacementTemplateData therefore uses the defaults unchanged.

Missing template variables

By default this mock matches SES's send behaviour: a variable referenced in a template but missing from the data renders as an empty string, and the send still succeeds (real SES accepts the request, returns a MessageId, and reports rendering failures asynchronously rather than as a synchronous API error).

If you would rather catch template/data mismatches locally, set the AWS_SES_STRICT_TEMPLATE_RENDERING=true environment variable. This makes a missing variable fail fast — a 400 for sendEmail, and a FAILED entry for sendBulkEmail. This is a deliberate divergence from SES, intended purely as a local debugging aid; leave it unset for parity.

testRenderEmailTemplate always fails fast (400) on a missing variable, regardless of this setting — real SES reports missing rendering attributes synchronously for this endpoint, since validating templates is its whole purpose.

Viewing emails

Navigate to the address and port where the server is running in your browser (e.g. localhost:8005).

Docker

A Dockerfile that bakes the /dist/cli.js is provided. There is also a docker-compose.yml template to create a container running the aws-ses-v2-local mock server.