emailjs-imap-client is a low-level JavaScript IMAP client designed to interact with IMAP servers for email management. It provides a programmatic interface for tasks like connecting, authenticating, listing mailboxes, fetching messages, and other standard IMAP operations. The current stable version is 3.1.0, released approximately six years ago. The library is currently in a maintenance state, as the original author is no longer actively maintaining it, and there's an open call for community contributions. This means new feature development and proactive bug fixes are sporadic or non-existent without community involvement. Its primary differentiator is being one of the few dedicated IMAP client implementations available for JavaScript environments, making it a critical component for applications requiring direct IMAP protocol interaction. It handles both plain and TLS-secured connections, with configurable STARTTLS behavior.
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
The primary `ImapClient` class is exported as a default export for ECMAScript Modules (ESM).
import ImapClient from 'emailjs-imap-client'
When using CommonJS modules (e.g., in Node.js environments prior to ESM adoption), the default export must be accessed via the `.default` property.
const ImapClient = require('emailjs-imap-client').default
For TypeScript users, it is recommended to use `import type` if only importing the type definition to prevent bundling unnecessary runtime code. This library provides implicit type inference, but explicit type declarations might be community-contributed.
import type ImapClient from 'emailjs-imap-client'
Demonstrates how to initialize the ImapClient, connect to a server with authentication, list mailboxes, select a mailbox, list messages, and handle basic errors, emphasizing security for passwords and instance reusability.
import ImapClient from 'emailjs-imap-client';
const host = 'localhost'; // Replace with your IMAP server host, e.g., 'imap.mail.com'
const port = 143; // Standard IMAP port (993 for IMAPS)
const username = 'testuser'; // Replace with your IMAP username
const password = process.env.IMAP_PASS ?? 'testpass'; // Use environment variable for real passwords in production
async function runImapClient() {
// Create a new client instance for each connection session due to reusability limitations.
const client = new ImapClient(host, port, {
auth: {
user: username,
pass: password
},
// Recommended for secure connections: useSecureTransport for IMAPS, requireTLS for STARTTLS.
// useSecureTransport: true, // For IMAPS (SSL/TLS on connection, typically port 993)
// requireTLS: true, // Force STARTTLS if server supports it, fail if not.
// ignoreTLS: true, // Use with extreme caution: allows plain text password over unencrypted connection.
// For self-signed certificates in dev/test, add:
// tls: { rejectUnauthorized: false }
});
client.logLevel = 'info'; // Set verbosity to 'error', 'warn', 'info', 'debug'
client.on('error', (err) => {
console.error('IMAP Client Error:', err);
});
try {
await client.connect();
console.log('Successfully connected to IMAP server.');
// Example: List all mailboxes
const mailboxes = await client.listMailboxes();
console.log('Available Mailboxes:');
mailboxes.forEach(mb => console.log(` - ${mb.name} (Delimiter: '${mb.delimiter}', Flags: ${mb.flags.join(', ')})`));
// Example: Select 'INBOX' and list messages (first 10)
console.log('\nSelecting INBOX...');
const mailboxStatus = await client.selectMailbox('INBOX');
console.log(`INBOX has ${mailboxStatus.exists} messages, ${mailboxStatus.unseen} unseen.`);
const messages = await client.listMessages('INBOX', '1:10', ['uid', 'flags', 'envelope']);
console.log('First 10 messages in INBOX:');
messages.forEach(msg => {
console.log(` UID: ${msg.uid}, Subject: ${msg.envelope.subject ?? '[No Subject]'}, From: ${msg.envelope.from?.[0]?.address ?? 'N/A'}`);
});
// Disconnect from the server
await client.logout();
console.log('Disconnected from IMAP server.');
} catch (error) {
console.error('Failed to connect or perform IMAP operation:', error);
// It's crucial to create a new client instance after an error if you want to retry.
}
}
runImapClient();
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.