eleithemailjs 📧✨
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, andXOAUTH2. - 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 emailjsRequirements
- 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 <your-email@example.com>',
to: 'Someone <someone@example.com>',
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 <your-email@example.com>',
to: 'Someone <someone@example.com>',
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: '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
};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:coverageDevelopment 🧑💻🌱
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 upMailpit 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 buildThen, 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.jsAfter running a script, open your Mailpit Web UI (http://localhost:8025) to
see the emails stream in! 📩