SES Easy Mailer

A powerful Node.js wrapper for Amazon Simple Email Service (SES) that simplifies sending transactional emails and newsletters.

Built specifically for AWS SES, it provides:

• ☁️ Worker Enviroment compatible (Like Cloudflare)
• 📧 Easy integration with Amazon SES templates
• 📁 Support for local HTML templates
• 👥 Bulk email sending with CC/BCC support
• 📎 File attachments handling
• ⚡ Optimized SES API usage
• 🔄 Template variable substitution
• 🚀 Promise-based async/await API

Perfect for applications needing to send transactional emails, newsletters, or any automated email communication through Amazon SES.

Installation

npm install ses-easy-mailer

Basic Usage

CommonJS

const SESMailer = require('ses-easy-mailer');

ES Modules

import SESMailer from 'ses-easy-mailer';

Initialize the mailer

const mailer = new SESMailer({
    region: "us-east-1",
    accessKeyId: "YOUR_KEY",
    secretAccessKey: "YOUR_SECRET"
});

// Optional: Set default sender
mailer.setDefaultSender('[email protected]');

Sending Emails

Using SES Templates

await mailer.sendTemplate({
    from: '[email protected]',          // Optional if default sender is set
    to: '[email protected]',         // String or array for multiple recipients
    cc: ['[email protected]'],            // Optional
    bcc: '[email protected]',             // Optional
    subject: 'Welcome!',
    templateName: 'WelcomeTemplate',     // Your SES template name
    templateData: {                      // Data for template variables
        name: 'John',
        company: 'Acme Inc'
    }
});

Using HTML String Templates

await mailer.sendFileTemplate({
    to: ['[email protected]', '[email protected]'],
    subject: 'Monthly Newsletter',
    templateContent: '<h1>Newsletter: {{month}}</h1><p>{{highlights}}</p>',
    templateData: {
        month: 'January',
        highlights: 'New Features'
    },
    attachments: [{
        filename: 'report.pdf',
        content: new Uint8Array(/* your pdf data */),
        contentType: 'application/pdf'  // optional, defaults to application/octet-stream
    }]
});

Using File Templates

await mailer.sendFileTemplate({
    to: ['[email protected]', '[email protected]'],
    subject: 'Monthly Newsletter',
    templatePath: './templates/newsletter.html',
    templateData: {
        month: 'January',
        highlights: 'New Features'
    },
    attachments: [{
        filename: 'report.pdf',
        content: Buffer.from(/* your pdf data */),
        encoding: 'base64'
    }]
});

Sending Raw Emails

await mailer.sendRawEmail({
    to: '[email protected]',
    subject: 'Quick Update',
    html: '<h1>Hello!</h1><p>This is a test email.</p>',
    text: 'Hello! This is a test email.' // Optional plain text version
});

API Reference

Constructor

const mailer = new SESMailer(sesClient);

Methods

setDefaultSender(email)

Sets a default sender email address for all emails.

mailer.setDefaultSender('[email protected]');

sendTemplate(options)

Sends an email using an SES template.

• options:
  • from: Sender email (optional if default set)
  • to: Recipient(s) email (string or array)
  • cc: CC recipient(s) (optional, string or array)
  • bcc: BCC recipient(s) (optional, string or array)
  • subject: Email subject
  • templateName: Name of the SES template
  • templateData: Object containing template variables
  • attachments: Array of attachment objects (optional)

sendFileTemplate(options)

Sends an email using an HTML file template or a string template.

• Options same as above, but uses templatePath or templateContent instead of templateName

sendRawEmail(options)

Sends a raw email with HTML/text content.

• Options same as above, but uses html and/or text instead of template options

Attachments

Attachment objects should follow this format:

{
    filename: 'document.pdf',
    content: new Uint8Array(/* file content */) // Can be ArrayBuffer, Uint8Array, or string
    contentType: 'application/pdf'  // Optional, defaults to application/octet-stream
}

Notes

• SES has limitations on attachment types
• Template placeholders use {{variableName}} syntax
• When using SES templates without attachments, the module uses SendTemplatedEmailCommand for better performance
• Binary attachments (ArrayBuffer/Uint8Array) and string content are automatically base64 encoded