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! 🛠️

$3

It's super simple!

``bash
npm install emailjs
`

$3

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

$3

Here's how easy it is to send emails:

#### Text-Only Emails

`javascript
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 ',
to: 'Someone ',
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

`javascript
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 =

Greetings!

This is an HTML email with a lovely picture and an attachment.

Check out the attached file!

;

const message = new Message({
from: 'You ',
to: 'Someone ',
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': '' },
},
],
});

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

$3

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

`javascript
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)
};
`

$3

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

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

$3

a promise-based way to send emails! ✨

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

$3

Constructs an RFC2822-compliant message object.

`javascript
const headers = {
from: 'sender@example.com', // 💌 Sender (required!)
to: 'recipient@example.com', // 📬 Recipients (at least one of to, cc, or bcc)
cc: 'carbon-copy@example.com', // 👥 CC recipients
bcc: 'blind-copy@example.com', // 🕵️‍♀️ BCC recipients
subject: 'Your Subject Here', // 📝 Email subject
text: 'Plain text body.', // 🗒️ Plain text content
attachment: [{ data: 'Hello!' }], // 📎 One or more attachments
};
`

$3

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

`javascript
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
});
`

$3

Synchronously validates that a Message is properly formed before sending.

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

Authors ✍️

* eleith
* zackschuster

Testing 🧪

`bash


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

$3

Ensure you have Docker and Docker Compose installed.

`bash


From the project root, start Mailpit


docker compose up
`

Mailpit will be accessible via:

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

$3

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:

`bash
npm run build
`

Then, run any of the example scripts:

`bash


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! 📩