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

import { SMTPClient } from 'emailjs';

const client = new SMTPClient({
    user: 'your-username',
    password: 'your-password',
    host: 'smtp.your-email.com',
    ssl: true, // Use SSL for secure connection
});

async function sendMyEmail() {
    try {
        const message = await client.sendAsync({
            text: 'Hello from emailjs! This is a test message.',
            from: 'You <[e-mail]>',
            to: 'Someone <[e-mail]>',
            subject: 'Exciting News from emailjs! 🎉',
        });
        console.log('Email sent successfully:', message);
    } catch (err) {
        console.error('Failed to send email:', err);
    } finally {
        client.smtp.close(); // Don't forget to close the connection!
    }
}

sendMyEmail();

HTML Emails & Attachments

import { SMTPClient, Message } from 'emailjs';

const client = new SMTPClient({
    user: 'your-username',
    password: 'your-password',
    host: 'smtp.your-email.com',
    tls: true,
});

async function sendRichEmail() {
    const htmlContent = `
        <h1>Greetings!</h1>
        <p>This is an <b>HTML email</b> with a lovely picture and an attachment.</p>
        <img src="cid:my-image" alt="Embedded Image" width="150" height="100">
        <p>Check out the attached file!</p>
    `;

    const message = new Message({
        from: 'You <[e-mail]>',
        to: 'Someone <[e-mail]>',
        subject: 'Your Awesome HTML Email! 🖼️📄',
        attachment: [
            {
                data: htmlContent,
                alternative: true, // This part is the HTML body
                contentType: 'text/html',
            },
            {
                path: 'path/to/your/document.pdf', // Attach a file from disk
                type: 'application/pdf',
                name: 'document.pdf',
            },
            {
                path: 'path/to/your/image.jpg', // Embed an image for the HTML
                type: 'image/jpeg',
                name: 'cool_image.jpg',
                // Reference in HTML with cid:my-image
                headers: { 'Content-ID': '<my-image>' },
            },
        ],
    });

    try {
        await client.sendAsync(message);
        console.log('Rich email sent successfully!');
    } catch (err) {
        console.error('Failed to send rich email:', err);
    } finally {
        client.smtp.close();
    }
}

sendRichEmail();

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.

const options = {
    user: 'your-username', // 🔑 Username for logging into SMTP
    password: 'your-password', // 🤫 Password for logging into SMTP
    host: 'smtp.your-email.com', // 🌐 SMTP server host (defaults to 'localhost')
    port: 587, // 🔌 SMTP port (defaults: 25 unencrypted, 465 SSL, 587 TLS)
    ssl: true, // 🔒 Boolean or object for immediate SSL connection
    tls: true, // 🔐 Boolean or object (see typescript types) to initiate STARTTLS
    timeout: 5000, // ⏳ Max milliseconds to wait for SMTP responses
    domain: 'your-domain.com', // 🏠 Domain to greet SMTP with (defaults to os.hostname)
    authentication: ['PLAIN', 'LOGIN'], // 🤝 Preferred authentication methods
    logger: console, // 📝 Override the built-in logger (e.g., custom logging)
};

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: '[e-mail]', // 💌 Sender (required!)
    to: '[e-mail]', // 📬 Recipients (at least one of to, cc, or bcc)
    cc: '[e-mail]', // 👥 CC recipients
    bcc: '[e-mail]', // 🕵️‍♀️ 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 <img src="cid:...">)
    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! 📩