Octomailer is a powerful, universal Node.js library for sending transactional emails. It provides a single, unified API to interact with multiple email service providers, allowing you to switch between them effortlessly and implement sophisticated sending strategies.
- Unified API: A simple, consistent API for all supported providers. No need to learn different SDKs.
- Weighted Load Balancing: Distribute your email sending across multiple providers based on weights you define. This is perfect for managing sending quotas or optimizing costs. For example, if SendGrid offers 100 free emails and Brevo offers 300, you can give Brevo a weight of 3 and SendGrid a weight of 1 to use Brevo three times more often.
- Provider Flexibility: Easily switch between providers without changing your application code.
- TypeScript Support: Written in TypeScript for a better developer experience with static typing and autocompletion.
- Extensible: Easily add your own custom providers.
| Provider | Free Tier |
|---|---|
| Resend | 3,000 emails/month (100 emails/day) |
| SendGrid | 100 emails/day |
| Brevo | 300 emails/day (9,000 emails/month) |
| Mailgun | 100 emails/day |
| Amazon SES | 3,000 messages/month for the first 12 months |
| Postmark | 100 emails/month |
| Mandrill | No free tier |
| SparkPost | 500 emails/month (for testing) |
| Infobip | 100 messages/day (60-day free trial) |
| Mailjet | 200 emails/day (6,000 emails/month) |
npm install octomailerHere's a simple example of how to use Octomailer with two providers:
import {
Octomailer,
SendGridProvider,
ResendProvider,
EmailOptions,
} from 'octomailer';
// 1. Initialize your chosen providers with their credentials and weights
const sendgridProvider = new SendGridProvider('YOUR_SENDGRID_API_KEY', 1);
const resendProvider = new ResendProvider('YOUR_RESEND_API_KEY', 3);
// 2. Create an instance of Octomailer with your providers
const mailer = new Octomailer([sendgridProvider, resendProvider]);
// 3. Define your email
const email: EmailOptions = {
to: 'recipient@example.com',
from: 'sender@example.com',
subject: 'Hello from Octomailer!',
text: 'This is the plain text body of the email.',
html: '<h1>This is the HTML body of the email.</h1>',
};
// 4. Send the email
mailer
.send(email)
.then(() => console.log('Email sent successfully!'))
.catch((error) => console.error('Error sending email:', error));Below are the details for configuring each supported provider.
- Website: resend.com
- Constructor:
new ResendProvider(apiKey: string, weight: number)
import { ResendProvider } from 'octomailer';
const provider = new ResendProvider('YOUR_RESEND_API_KEY', 1);- Website: sendgrid.com
- Constructor:
new SendGridProvider(apiKey: string, weight: number)
import { SendGridProvider } from 'octomailer';
const provider = new SendGridProvider('YOUR_SENDGRID_API_KEY', 1);- Website: brevo.com
- Constructor:
new BrevoProvider(apiKey: string, weight: number)
import { BrevoProvider } from 'octomailer';
const provider = new BrevoProvider('YOUR_BREVO_API_KEY', 3);- Website: mailgun.com
- Constructor:
new MailgunProvider(apiKey: string, domain: string, weight: number)
import { MailgunProvider } from 'octomailer';
const provider = new MailgunProvider(
'YOUR_MAILGUN_API_KEY',
'YOUR_MAILGUN_DOMAIN',
2,
);- Website: aws.amazon.com/ses
- Constructor:
new SESProvider(region: string, accessKeyId: string, secretAccessKey: string, weight: number)
import { SESProvider } from 'octomailer';
const provider = new SESProvider(
'us-east-1',
'YOUR_AWS_ACCESS_KEY_ID',
'YOUR_AWS_SECRET_ACCESS_KEY',
4,
);- Website: postmarkapp.com
-. Constructor:
new PostmarkProvider(serverToken: string, weight: number)
import { PostmarkProvider } from 'octomailer';
const provider = new PostmarkProvider('YOUR_POSTMARK_SERVER_TOKEN', 1);- Website: mailchimp.com/mandrill
- Constructor:
new MandrillProvider(apiKey: string, weight: number)
import { MandrillProvider } from 'octomailer';
const provider = new MandrillProvider('YOUR_MANDRILL_API_KEY', 1);- Website: infobip.com
- Constructor:
new InfobipProvider(apiKey: string, baseUrl: string, weight: number)
import { InfobipProvider } from 'octomailer';
const provider = new InfobipProvider(
'YOUR_INFOBIP_API_KEY',
'YOUR_INFOBIP_BASE_URL',
2,
);- Website: mailjet.com
- Constructor:
new MailjetProvider(apiKey: string, apiSecret: string, weight: number)
import { MailjetProvider } from 'octomailer';
const provider = new MailjetProvider(
'YOUR_MAILJET_API_KEY',
'YOUR_MAILJET_API_SECRET',
2,
);- Website: sparkpost.com
- Constructor:
new SparkPostProvider(apiKey: string, weight: number)
import { SparkPostProvider } from 'octomailer';
const provider = new SparkPostProvider('YOUR_SPARKPOST_API_KEY', 1);Creates a new Octomailer instance.
providers: An array of instantiated provider objects.
Sends an email using one of the configured providers, selected based on their weight.
options: AnEmailOptionsobject containing the email details.
interface EmailOptions {
to: string;
from: string;
subject: string;
text: string;
html?: string;
attachments?: EmailAttachment[];
}
interface EmailAttachment {
filename: string;
content: string;
contentType: string;
}This is the interface that all providers must implement.
interface Provider {
name: string;
weight: number;
send(options: EmailOptions): Promise<EmailResult>;
}To get started with development:
- Clone the repository.
- Install dependencies:
npm install - Run the tests:
npm test - Build the project:
npm run build
npm test: Run the tests.npm run test:watch: Run the tests in watch mode.npm run build: Build the project.npm run lint: Lint the code.npm run format: Format the code.
Contributions are welcome! Please feel free to submit a pull request or open an issue.
This project is licensed under the ISC License. See the LICENSE file for details.