EmailJS IMAP Client

Common errors

• Error: Self-signed certificate in certificate chain

  cause The IMAP server uses a self-signed TLS certificate or one issued by an untrusted Certificate Authority (CA), which the client's TLS stack does not recognize.
  fix For development or testing, you can set `tls: { rejectUnauthorized: false }` in the options object of `ImapClient` (use with extreme caution in production as it bypasses certificate validation). For production, ensure the IMAP server uses a certificate from a trusted CA, or configure your system/environment to trust the custom CA if applicable.

• Error: AUTHENTICATION FAILED

  cause The provided username, password, or OAuth2 access token in the `auth` options is incorrect or the IMAP server rejected the authentication attempt for another reason (e.g., account locked, app-specific password required).
  fix Double-check the `auth.user` and `auth.pass` (or `auth.xoauth2`) values for typos. Verify credentials directly with the IMAP server using another client if possible. Check server-side logs for more specific authentication failure reasons, and ensure the account doesn't require specific app passwords or two-factor authentication bypasses.

• Error: Client connection terminated unexpectedly

  cause The IMAP server closed the TCP connection prematurely, possibly due to a timeout, an invalid command from the client, too many failed attempts, or underlying network instability. This can also happen if the server enforces idle timeouts.
  fix Check network connectivity to the IMAP server. Review server logs for specific error messages. Ensure your client's commands adhere strictly to the IMAP protocol. Remember that `ImapClient` instances are not reusable; if the connection drops, a new instance must be created to reconnect. Consider implementing a robust retry mechanism with new client instances.

Warnings

• gotcha ImapClient instances cannot be reused. After a connection is terminated (either intentionally via `logout()` or `close()`, or due to an error), a new `ImapClient` instance must be created for subsequent operations. Reattempting to use a disconnected or errored instance will lead to unexpected behavior and potential errors.
  Fix: Always create a new `new ImapClient(...)` instance after a connection is closed or fails, before attempting to reconnect or perform new operations. Do not try to reconnect with an old instance.
• gotcha The library is not actively maintained by its original author. While functional, future feature development, proactive bug fixes, and updates to the IMAP protocol or underlying dependencies are reliant on community contributions. This poses a long-term risk for new projects or those requiring active support.
  Fix: Evaluate the current state against project needs. Be prepared to contribute fixes or features, or consider forking if dedicated maintenance is required. Monitor the GitHub repository for new maintainers and community activity.
• gotcha Default STARTTLS support is opportunistic. If the server advertises STARTTLS, the client attempts to use it. If not, credentials might be sent in plain text over an unencrypted connection, which is a significant security risk. For explicit security, always configure `useSecureTransport`, `requireTLS`, or `ignoreTLS` carefully.
  Fix: For secure connections, explicitly set `options.useSecureTransport: true` for IMAPS (SSL/TLS on connection, typically port 993) or `options.requireTLS: true` to enforce STARTTLS. Use `options.ignoreTLS: true` only if you fully understand the security implications and accept plain-text communication.
• breaking Future versions are planned to remove the 'emailjs-tcp-socket' shim in favor of Node.js's native 'net' and 'tls' modules. This change will primarily affect the internal implementation, but could potentially break environments or custom setups that rely on the shim's specific behavior or browser compatibility strategies.
  Fix: Monitor future release notes closely. If you have custom socket implementations or browser environments currently using the `emailjs-tcp-socket` shim, be prepared for potential adjustments and ensure compatibility once this breaking change is introduced.

Install

• npm install emailjs-imap-client npm
• yarn add emailjs-imap-client yarn
• pnpm add emailjs-imap-client pnpm

Imports

• ImapClient
  wrong:

  import { ImapClient } from 'emailjs-imap-client'

  correct:

  import ImapClient from 'emailjs-imap-client'

  The primary `ImapClient` class is exported as a default export for ECMAScript Modules (ESM).
• ImapClient (CommonJS)
  wrong:

  const ImapClient = require('emailjs-imap-client')

  correct:

  const ImapClient = require('emailjs-imap-client').default

  When using CommonJS modules (e.g., in Node.js environments prior to ESM adoption), the default export must be accessed via the `.default` property.
• ImapClient (Type)

  import type ImapClient from 'emailjs-imap-client'

  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.

Quickstart

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();