{"id":13324,"library":"imap-simple","title":"Simple IMAP Client Wrapper","description":"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.","status":"abandoned","version":"5.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/chadxz/imap-simple","tags":["javascript","imap","node-imap"],"install":[{"cmd":"npm install imap-simple","lang":"bash","label":"npm"},{"cmd":"yarn add imap-simple","lang":"bash","label":"yarn"},{"cmd":"pnpm add imap-simple","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency providing the underlying IMAP client functionality. `imap-simple` is a wrapper around this library.","package":"node-imap","optional":false},{"reason":"Often used in examples for utility functions like object manipulation when processing email parts, particularly for finding specific body parts.","package":"lodash","optional":true},{"reason":"Recommended for robust parsing of raw email content, headers, and attachments, as `imap-simple` provides raw message parts that need further processing.","package":"mailparser","optional":true}],"imports":[{"note":"The library primarily exports a single default object containing the `connect` function and other utilities. Named imports for `connect` will fail.","wrong":"import { connect } from 'imap-simple';","symbol":"imaps","correct":"import imaps from 'imap-simple';"},{"note":"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`.","wrong":"const { connect } = require('imap-simple');","symbol":"require_cjs_main_export","correct":"const imaps = require('imap-simple');"},{"note":"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`.","wrong":"import { Connection } from 'imap-simple';","symbol":"ImapConnection","correct":"import imaps from 'imap-simple';\n// After connecting: const connection = await imaps.connect(config);"}],"quickstart":{"code":"import imaps from 'imap-simple';\n\nconst config = {\n    imap: {\n        user: process.env.IMAP_USER ?? '',\n        password: process.env.IMAP_PASSWORD ?? '',\n        host: process.env.IMAP_HOST ?? 'imap.gmail.com',\n        port: parseInt(process.env.IMAP_PORT ?? '993', 10),\n        tls: (process.env.IMAP_TLS ?? 'true') === 'true',\n        authTimeout: parseInt(process.env.IMAP_AUTH_TIMEOUT ?? '3000', 10)\n    }\n};\n\nimaps.connect(config)\n    .then(function (connection) {\n        console.log('Connected to IMAP server.');\n        return connection.openBox('INBOX')\n            .then(function (box) {\n                console.log(`Opened box: ${box.name}`);\n                const searchCriteria = ['UNSEEN'];\n                const fetchOptions = {\n                    bodies: ['HEADER'],\n                    markSeen: false\n                };\n                return connection.search(searchCriteria, fetchOptions);\n            });\n    })\n    .then(function (results) {\n        const subjects = results.map(function (res) {\n            const headerPart = res.parts.find(part => part.which === 'HEADER');\n            return headerPart ? headerPart.body.subject[0] : '[No Subject]';\n        });\n        console.log('Subjects of unread emails:', subjects);\n    })\n    .catch(function (err) {\n        console.error('IMAP operation failed:', err);\n        process.exit(1);\n    });\n","lang":"javascript","description":"Demonstrates connecting to an IMAP server using environment variables for authentication and retrieving the subject lines of all unread emails from the INBOX."},"warnings":[{"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.","message":"The `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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Carefully review the `imap-simple` API documentation for limitations. For advanced features or when encountering missing functionality, consider using `node-imap` directly.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate security implications carefully. If continued use is unavoidable, perform a thorough security audit. Ideally, migrate to a supported and actively maintained library.","message":"Due 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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: Self-signed certificate in certificate chain"},{"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.","cause":"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.","error":"Error: Authentication failed"},{"fix":"Ensure `const imaps = require('imap-simple');` (CommonJS) or `import imaps from 'imap-simple';` (ES Modules) is used correctly, and then call `imaps.connect(...)`.","cause":"The `imap-simple` module was not correctly imported or required, meaning the `connect` function is not accessible on the `imaps` object.","error":"TypeError: Cannot read properties of undefined (reading 'connect')"},{"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.","cause":"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.","error":"Error: read ECONNRESET"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}