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:

JavaScript/TypeScript for the V2 API with the V3 SDK (recommended)

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: 'sender@example.com',
    Destination: { ToAddresses: ['receiver@example.com'] },
    Content: {
        Simple: {
            Subject: { Data: 'This is the subject' },
            Body: { Text: { Data: 'This is the email contents' } },
        }
    },
}))

JavaScript/TypeScript for the V1 API with the V3 SDK

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: 'sender@example.com',
    Destination: { ToAddresses: ['receiver@example.com'] },
    Message: {
        Subject: { Data: 'This is the subject' },
        Body: { Text: { Data: 'This is the email contents' } },
    },
}))

JavaScript/TypeScript for the V2 API with the V2 SDK

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: 'sender@example.com',
    Destination: { ToAddresses: ['receiver@example.com'] },
    Content: {
        Simple: {
            Subject: { Data: 'This is the subject' },
            Body: { Text: { Data: 'This is the email contents' } },
        }
    },
})

JavaScript/TypeScript with nodemailer for the V1 raw API with the V3 SDK

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: 'sender@example.com',
    to: ['receiver@example.com'],
    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 follows SES's whole-object fallback: DefaultContent.TemplateData is used for an entry only when that entry's ReplacementTemplateData is empty ({}) or absent. Once an entry supplies any replacement data, it is used on its own — the defaults are not merged in per key.

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.