https://github.com/chihebnabil/ses-easy-mailer
A simple and easy-to-use mailer module for Amazon SES.
https://github.com/chihebnabil/ses-easy-mailer
aws-ses cloudflare-workers nodejs npm-package
Last synced: about 1 month ago
JSON representation
A simple and easy-to-use mailer module for Amazon SES.
- Host: GitHub
- URL: https://github.com/chihebnabil/ses-easy-mailer
- Owner: chihebnabil
- Created: 2024-02-01T10:31:08.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-03T21:19:59.000Z (about 2 months ago)
- Last Synced: 2025-05-05T03:44:53.189Z (about 1 month ago)
- Topics: aws-ses, cloudflare-workers, nodejs, npm-package
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/ses-easy-mailer
- Size: 112 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# 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
```bash
npm install ses-easy-mailer
```
## Basic Usage
### CommonJS
```javascript
const SESMailer = require('ses-easy-mailer');
const { SESClient } = require('@aws-sdk/client-ses');
```
### ES Modules
```javascript
import SESMailer from 'ses-easy-mailer';
import { SESClient } from '@aws-sdk/client-ses';
```
## Initialize SES client
```javascript
const client = new SESClient({
region: "us-east-1",
credentials: {
accessKeyId: "YOUR_KEY",
secretAccessKey: "YOUR_SECRET",
}
});
```
## Create mailer instance
```javascript
const mailer = new SESMailer(client);
// Optional: Set default sender
mailer.setDefaultSender('[email protected]');
```
## Sending Emails
### Using SES Templates
```javascript
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 File Templates
```javascript
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
```javascript
await mailer.sendRawEmail({
to: '[email protected]',
subject: 'Quick Update',
html: '
Hello!
This is a test email.
',
text: 'Hello! This is a test email.' // Optional plain text version
});
```
## API Reference
### Constructor
```javascript
const mailer = new SESMailer(sesClient);
```
### Methods
#### setDefaultSender(email)
Sets a default sender email address for all emails.
```javascript
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.
- Options same as above, but uses `templatePath` 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:
```javascript
{
filename: 'document.pdf',
content: Buffer.from(/* file content */),
encoding: 'base64' // Optional, defaults to base64
}
```
## Notes
- SES has [limitations on attachment types](https://docs.aws.amazon.com/ses/latest/dg/mime-types.html)
- Template placeholders use `{{variableName}}` syntax
- When using SES templates without attachments, the module uses `SendTemplatedEmailCommand` for better performance