imap-simple

library5.1.0jsnpmunverified

imap-simple (version 5.1.0) is a JavaScript library designed to provide a simplified, promise-based API over `node-imap`, a robust IMAP client for Node.js. It aims to streamline common email interaction tasks like fetching message headers, body content, and attachments, by abstracting away some complexities of the underlying `node-imap` library. However, the library is explicitly stated as unmaintained and archived, meaning it receives no further updates or support, and is missing significant functionality present in `node-imap`. Its development pace was inconsistent, and current usage is strongly discouraged due to its abandonment and lack of updates for security or compatibility. While it offered a promise-based API and simplified call structure, these benefits are now significantly outweighed by its unmaintained status and potential compatibility issues with modern Node.js environments.

communication

npm install imap-simple

github ↗package ↗

INSTALL

IMPORT

SIG · IMAP-SIMPLE

imap-simple

communicationjavascriptv5.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

imaps

✓ import imaps from 'imap-simple';

✗ import { connect } from 'imap-simple';

The library primarily exports a single default object containing the `connect` function and other utilities. Named imports for `connect` will fail.

require_cjs_main_export

✓ const imaps = require('imap-simple');

✗ const { connect } = require('imap-simple');

In CommonJS, the module exports an object directly. You should assign the entire module export to a variable (e.g., `imaps`) and then access its methods like `imaps.connect`.

ImapConnection

✓ import imaps from 'imap-simple'; // After connecting: const connection = await imaps.connect(config);

✗ import { Connection } from 'imap-simple';

The `Connection` object returned by `imaps.connect` is an instance, not a named export. Its type (if using TypeScript) would typically be inferred or derived from the return type of `connect`.

Demonstrates connecting to an IMAP server using environment variables for authentication and retrieving the subject lines of all unread emails from the INBOX.

import imaps from 'imap-simple'; const config = { imap: { user: process.env.IMAP_USER ?? '', password: process.env.IMAP_PASSWORD ?? '', host: process.env.IMAP_HOST ?? 'imap.gmail.com', port: parseInt(process.env.IMAP_PORT ?? '993', 10), tls: (process.env.IMAP_TLS ?? 'true') === 'true', authTimeout: parseInt(process.env.IMAP_AUTH_TIMEOUT ?? '3000', 10) } }; imaps.connect(config) .then(function (connection) { console.log('Connected to IMAP server.'); return connection.openBox('INBOX') .then(function (box) { console.log(`Opened box: ${box.name}`); const searchCriteria = ['UNSEEN']; const fetchOptions = { bodies: ['HEADER'], markSeen: false }; return connection.search(searchCriteria, fetchOptions); }); }) .then(function (results) { const subjects = results.map(function (res) { const headerPart = res.parts.find(part => part.which === 'HEADER'); return headerPart ? headerPart.body.subject[0] : '[No Subject]'; }); console.log('Subjects of unread emails:', subjects); }) .catch(function (err) { console.error('IMAP operation failed:', err); process.exit(1); });

Debug

Known issues

breakingThe `imap-simple` library is officially unmaintained and has been archived. This means no new features, bug fixes, or security patches will be released. Using it in production is highly discouraged due to potential vulnerabilities and lack of support.

fix

Migrate to directly using `node-imap` or another actively maintained IMAP client library like `node-imap-client` or consider integrating with full-featured email processing services.

affects: >=5.0.0

gotchaThis library is a simplified wrapper over `node-imap` and explicitly states it is missing a great deal of functionality from its underlying dependency. Complex IMAP operations or specific flag manipulations may not be supported directly.

fix

Carefully review the `imap-simple` API documentation for limitations. For advanced features or when encountering missing functionality, consider using `node-imap` directly.

affects: >=1.0.0

gotchaDue to its unmaintained status, `imap-simple` might have compatibility issues with newer Node.js versions, updated IMAP server protocols (e.g., OAuth2), or introduce security vulnerabilities that remain unpatched. Its `engines` field specifies Node.js `>=6`, which is significantly outdated.

fix

Evaluate security implications carefully. If continued use is unavoidable, perform a thorough security audit. Ideally, migrate to a supported and actively maintained library.

affects: >=5.0.0

Errors

Common errors & fixes

Error: Self-signed certificate in certificate chain

The IMAP server is using a self-signed SSL/TLS certificate, or its certificate chain cannot be fully validated by the operating system's trust store, often in non-production environments.

fix

For development, you can add `tlsOptions: { rejectUnauthorized: false }` to your `imap` configuration (use with extreme caution in production). For production, ensure the server has a valid, trusted SSL certificate.

Error: Authentication failed

Incorrect username, password, or IMAP server settings (e.g., host, port, TLS configuration). Some email providers require app-specific passwords or OAuth2 instead of standard credentials.

fix

Double-check your `user` and `password`. Verify `host`, `port`, and `tls` settings. For services like Gmail, ensure 'Less secure app access' is enabled or use an app password.

TypeError: Cannot read properties of undefined (reading 'connect')

The `imap-simple` module was not correctly imported or required, meaning the `connect` function is not accessible on the `imaps` object.

fix

Ensure `const imaps = require('imap-simple');` (CommonJS) or `import imaps from 'imap-simple';` (ES Modules) is used correctly, and then call `imaps.connect(...)`.

Error: read ECONNRESET

The connection to the IMAP server was abruptly terminated by the server itself or an intermediate network device (e.g., firewall), often due to inactivity, incorrect protocol, or network instability.

fix

Check network connectivity, firewall rules, and IMAP server logs. Consider increasing `authTimeout` or implementing retry logic for transient network issues. Verify port and TLS settings are correct for your server.

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

node-imaprequiredCore dependency providing the underlying IMAP client functionality. `imap-simple` is a wrapper around this library.

lodashoptionalOften used in examples for utility functions like object manipulation when processing email parts, particularly for finding specific body parts.

mailparseroptionalRecommended for robust parsing of raw email content, headers, and attachments, as `imap-simple` provides raw message parts that need further processing.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/chadxz/imap-simple ↗

packagehttps://www.npmjs.com/package/imap-simple ↗