emailjs

emailjs ✨

Send emails with ease!

This library lets you send rich HTML emails, attachments (from files, streams, or strings), and plain text messages to any SMTP server.

What's to expect from emailjs?

• SSL and TLS Support: Secure connections to your SMTP servers.
• Authentication Galore: Supports popular SMTP authentication methods like PLAIN, LOGIN, CRAM-MD5, and XOAUTH2.
• Asynchronous Sending: Emails are queued and sent in the background.
• Rich Content: Send HTML emails and include multiple attachments.
• Flexible Attachments: Attachments can be files, data streams, or plain strings.
• UTF-8 Ready: Full support for UTF-8 in headers and body.
• Built-in Type Declarations: first-class TypeScript support.
• Greylisting Awareness: Automatically handles greylisting to improve deliverability.

Get Started! ️

Installing

It's super simple!

npm install emailjs

Requirements

• Access to an SMTP Server.
• If your email service (like Gmail) uses two-step verification, you'll need an application-specific password.

Quick Examples ‍

Here's how easy it is to send emails:

Text-Only Emails

…

HTML Emails & Attachments

…

API Reference

The emailjs library is fully typed, here is a brief overview of most likely to be used methods

new SMTPClient(options)

Create a new client instance to connect to your SMTP server.

…

SMTPClient#send(message, callback)

Sends an email message. You can pass a Message instance or a headers object.

client.send(messageObject, (err, details) => {
    if (err) console.error(err);
    else console.log('Message sent:', details);
});

SMTPClient#sendAsync(message)

a promise-based way to send emails! ✨

try {
    const details = await client.sendAsync(messageObject);
    console.log('Message sent:', details);
} catch (err) {
    console.error('Failed to send:', err);
}

new Message(headers)

Constructs an RFC2822-compliant message object.

const headers = {
    from: '[email protected]', //  Sender (required!)
    to: '[email protected]', //  Recipients (at least one of to, cc, or bcc)
    cc: '[email protected]', //  CC recipients
    bcc: '[email protected]', // ️‍♀️ BCC recipients
    subject: 'Your Subject Here', //  Email subject
    text: 'Plain text body.', // ️ Plain text content
    attachment: [{ data: 'Hello!' }], //  One or more attachments
};

Message#attach(options)

Adds an attachment to the message. Can be called multiple times.

message.attach({
    path: 'path/to/file.zip', //  Path to a file on disk
    data: 'Binary content as string or buffer', //  Raw data
    stream: fs.createReadStream('file.jpg'), //  A readable stream
    type: 'application/zip', // MIME type
    name: 'custom-name.zip', // Filename perceived by recipient
    alternative: true, // attach inline as an alternative (e.g., HTML body)
    inline: true, // If true, attached inline (e.g., for )
    headers: { 'X-Custom-Header': 'value' }, // Custom attachment headers
});

Message#checkValidity()

Synchronously validates that a Message is properly formed before sending.

const { isValid, validationError } = message.checkValidity();
if (!isValid) {
    console.error('Message is invalid:', validationError);
}

Authors ✍️

• eleith
• zackschuster

Testing

# Run all tests
npm test

# Run tests with code coverage report
npm run test:coverage

Development ‍

for a local smtp testing experience, use our Mailpit compose service

1. Start Mailpit with Docker Compose

Ensure you have Docker and Docker Compose installed.

# From the project root, start Mailpit
docker compose up

Mailpit will be accessible via:

• Web UI: http://localhost:8025
• SMTP Server: localhost:1025

2. Run Example Sending Scripts

You can use the provided scripts to send different types of emails to your local Mailpit instance.

First, make sure the emailjs library is built:

npm run build

Then, run any of the example scripts:

# Send a plain text email
node scripts/send-text.js

# Send an HTML email
node scripts/send-html.js

# Send an email with attachments
node scripts/send-attachment.js

After running a script, open your Mailpit Web UI (http://localhost:8025) to see the emails stream in!