Registry / communication / node-pop3

node-pop3

JSON →
library0.11.0jsnpmunverified

Node-pop3 is a JavaScript client library for the Post Office Protocol version 3 (POP3), designed for use in Node.js environments. It provides functionalities to connect to POP3 servers, authenticate users, list messages, retrieve mail content, and manage mailboxes. The library supports both Promise-based asynchronous operations for cleaner code and Node.js Streams for efficient handling of potentially large mail bodies. Version `0.11.0` is the current stable release, requiring Node.js `^20.11.0 || >= 22.0.0`. It ships with TypeScript type definitions, enhancing development experience for TypeScript users. Key differentiators include its explicit support for modern JavaScript constructs like Promises and Streams, along with a simple command-line interface (CLI) for testing. While similar libraries exist, node-pop3 aims for a direct API mirroring the POP3 protocol, rather than a high-level abstraction.

npm install node-pop3
INSTALL
IMPORT
SIG · NODE-POP3
N
node-pop3
communicationjavascriptv0.11.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

Pop3Command
import Pop3Command from 'node-pop3';
const Pop3Command = require('node-pop3').default;
The library primarily uses ESM `import` in its examples, though CommonJS `require` is also supported as shown in the README. When using `require`, it directly returns the `Pop3Command` constructor.
Pop3Command.stream2String
import Pop3Command from 'node-pop3'; /* ... */ const streamString = await Pop3Command.stream2String(retrStream);
import { stream2String } from 'node-pop3';
`stream2String` is a static helper method on the `Pop3Command` class, not a named export. It is used to convert a response stream into a string.
Pop3Command.listify
import Pop3Command from 'node-pop3'; /* ... */ const list = Pop3Command.listify(streamString);
import { listify } from 'node-pop3';
`listify` is a static helper method on the `Pop3Command` class, used for parsing multi-line server responses into structured arrays.

This quickstart demonstrates how to connect to a POP3 server, authenticate, retrieve mailbox statistics, list message UIDs, and fetch the content of the first message, finally disconnecting. It uses environment variables for credentials and showcases error handling.

import Pop3Command from 'node-pop3'; import 'dotenv/config'; // For loading environment variables async function fetchMail() { const user = process.env.POP3_USER ?? 'example@example.com'; const password = process.env.POP3_PASSWORD ?? 'your-password'; const host = process.env.POP3_HOST ?? 'pop3.example.com'; const port = parseInt(process.env.POP3_PORT ?? '995', 10); // Default to 995 for TLS const tls = process.env.POP3_TLS === 'true'; const pop3 = new Pop3Command({ user, password, host, port, tls }); try { await pop3.connect(); console.log('Connected to POP3 server.'); // Authenticate (handled by constructor in common methods like RETR/UIDL) // For manual command, you would do: // await pop3.command('USER', user); // await pop3.command('PASS', password); const [statInfo] = await pop3.command('STAT'); console.log(`Mailbox status: ${statInfo}`); // e.g., '100 102400' const list = await pop3.UIDL(); console.log('Messages in mailbox (UIDL):', list); if (list.length > 0) { const firstMsgNum = list[0][0]; console.log(`Retrieving message number ${firstMsgNum}...`); const mailContent = await pop3.RETR(firstMsgNum); console.log('\n--- First Mail Content ---\n'); console.log(mailContent.substring(0, 500) + '...'); // Log first 500 chars console.log('\n--------------------------\n'); } else { console.log('No messages in mailbox.'); } const [quitInfo] = await pop3.QUIT(); console.log(`Disconnected: ${quitInfo}`); } catch (error) { console.error('An error occurred:', error.message); if (error.eventName) { console.error('Event Name:', error.eventName); } if (error.command) { console.error('Command causing error:', error.command); } } } fetchMail();
pop3 --version
Debug
Known issues
gotchaWhen using the low-level `pop3.command()` method, the sequence of commands is critical and must follow the POP3 protocol state machine (e.g., `connect` -> `USER` -> `PASS` before `STAT` or `RETR`). Misordering these commands will result in protocol errors from the server.
fix
Ensure commands like `USER`, `PASS`, `STAT`, `RETR`, `QUIT` are executed in the correct POP3 protocol order. Higher-level methods like `RETR` or `UIDL` handle the `USER`/`PASS` authentication internally after `connect`.
affects: >=0.1.0
gotchaError objects thrown by `node-pop3` may contain additional diagnostic properties like `err.eventName` (e.g., `error`, `close`, `timeout`, `end`, `bad-server-response`, `no-socket`) and `err.command`, which provide context about the network event or command that triggered the error.
fix
Inspect `error.eventName` and `error.command` properties on caught exceptions for more granular error handling and debugging specific network or command-related issues.
affects: >=0.1.0
gotchaThe `tlsOptions` parameter in the `Pop3Command` constructor is passed directly to Node.js's `tls.connect` function. The accepted options and their behavior can vary slightly between different Node.js major versions.
fix
Refer to the official Node.js `tls.connect` documentation for your specific Node.js version when configuring `tlsOptions` to ensure compatibility and correct behavior.
affects: >=0.1.0
Errors
Common errors & fixes
-ERR [AUTH] Username and password not accepted.
Incorrect username or password provided to the POP3 server, or the account is not configured for POP3 access.
fix
Double-check `user` and `password` credentials. Verify that POP3 access is enabled for the email account on the mail server. Ensure `tls` option is correctly set if the server requires an SSL/TLS connection.
Error: read ECONNRESET
The connection to the POP3 server was unexpectedly reset, often due to a network issue, server overload, or an abrupt server-side disconnection.
fix
Check network connectivity and firewall rules. Ensure the POP3 server is accessible and not under heavy load. Implement retry logic with exponential backoff for transient network issues.
Error: connect ETIMEDOUT
The client attempted to connect to the POP3 server, but the connection timed out before it could be established, often indicating the server is unreachable or unresponsive on the specified host/port.
fix
Verify `host` and `port` are correct. Confirm the POP3 server is running and accessible from the client's network. Check firewall settings on both client and server sides.
Error: no-socket
The `command` method was called when there was no active socket connection, usually before `pop3.connect()` or after `pop3.QUIT()`.
fix
Ensure `await pop3.connect()` completes successfully before attempting to send any commands. Do not send commands after `await pop3.QUIT()`.
Upgrade
Version history
0.11.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
12
OpenAI (training)
1
Resources