# node-pop3

> POP3 client for node

Latest version **0.15.3** (published 2026-09-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-pop3
pnpm add node-pop3
yarn add node-pop3
bun add node-pop3
```

Provides the command `pop`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.15.3 |
| Published | 2026-09-16 |
| First published | 2016-07-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^20.11.0 \|\| >= 22.0.0 |
| Dependencies | 0 |
| Unpacked size | 115.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 33 |
| Author | lianxh |
| Maintainers | brettz9, lianxh |
| Keywords | pop3, node, Promise, Stream |

## Links

- npm: https://www.npmjs.com/package/node-pop3
- Repository: https://github.com/lianxh/node-pop3
- Homepage: https://github.com/lianxh/node-pop3#readme
- Issues: https://github.com/lianxh/node-pop3/issues
- npm.io page: https://npm.io/package/node-pop3

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 0.15.3 (latest) — 2026-09-16
- 0.15.2 — 2026-09-16
- 0.15.1 — 2026-09-11
- 0.15.0 — 2026-07-27
- 0.14.0 — 2026-07-27
- 0.13.0 — 2026-07-27
- 0.12.0 — 2026-07-27
- 0.11.0 — 2025-12-21
- 0.10.1 — 2025-12-17
- 0.10.0 — 2025-09-26
- 0.9.1 — 2025-04-14
- 0.9.0 — 2023-05-24
- 0.8.0 — 2022-01-16
- 0.7.0 — 2021-10-22
- 0.6.0 — 2020-08-10
- … 5 more at https://npm.io/package/node-pop3/versions

## README

# node-pop3

[pop3](https://tools.ietf.org/html/rfc1939) command support for node.
Supports **Promise** and **stream**.

## CLI

e.g. Test the API about `TOP`

`pop -u example@gmail.com -p pwd -h example.pop.com -m TOP 100 10`

or pass in some or all of the config in a designated config file (JSON or JS):

`pop -c pop.config.js -m TOP 100 10`

For more detail, please input

`pop --help`

## Usage

In CommonJS, you can get the `Pop3Command` as follows:

```js
const Pop3Command = require('node-pop3');
```

The examples below, however, use the [ESM Modules](https://nodejs.org/api/esm.html)
format instead (i.e., `import`).

## Example

- Fetch mail by msgNum:

```js
import Pop3Command from 'node-pop3';

const pop3 = new Pop3Command({
  user: 'example@example.com',
  password: 'example',
  host: 'pop3.example.com'
});

const msgNum = 1;

const str = await pop3.RETR(msgNum);
// deal with mail string
await pop3.QUIT();
```

- List msgNum to uid in Server

```js
const list = await pop3.UIDL();
console.dir(list);
/*
 * [
 *  ['1', 'ZC0113-H8wi_YChVab4F0QTbwP4B6i'],
 *  ['2', 'ZC0114-3A9gAn8M2Sp1RhVCGTIII6i'],
 *  ...
 * ]
*/
```

## API

* constructor(options)

params|optional|comment
---|---|---
options.user|no|String
options.password|no|String
options.host|no|String
options.port|yes|Number. Defaults to `110`
options.servername|yes|String. Defaults to `host` value. Same as `servername` for Node TLS option.
options.tls|yes|Boolean. Defaults to `false`
options.timeout|yes|Number. Defaults to `undefined`
options.maxMailSize|yes|Number (bytes). If exceeded while parsing `RETR`/`TOP`, rejects with `mailSizeExceeded`
options.parseStreamToString|yes|Boolean. Defaults to `true`. When `false`, `RETR`/`TOP` resolve to the raw stream
options.streamReadTimeout|yes|Number (ms). Timeout used while converting `RETR`/`TOP` stream to string
options.tlsOptions|yes|Defaults to `{}`

`tlsOptions` takes the options documented for your Node version and
`tls.connect` function.

* basic

method|params|return
---|---|---
connect||`{Promise}` resolve to `undefined`
command|`{String*}` command messages to Server|`{Promise}` resolve to `{Array[String, Stream]}`, which are messages of response and stream of response (if the response has multiple lines) from Server
listify|Splits lines by CRLF, filters out empty lines, and converts each line to a an array based on splitting by spaces

```js
const pop3 = new Pop3Command({host: 'pop3.example.com'});

// These must be in order
await pop3.connect();
await pop3.command('USER', 'example@example.com');
await pop3.command('PASS', 'example');

const [statInfo] = await pop3.command('STAT');
const [retrInfo, retrStream] = await pop3.command('RETR', 1);

console.log(statInfo); // 100 102400
console.log(retrInfo); // 1024 octets

const [quitInfo] = await pop3.command('QUIT');
console.log(quitInfo); // Logging out.

const streamString = await Pop3Command.stream2String(retrStream);
console.log(streamString); // <message details...>

console.log(
  await Pop3Command.listify(streamString)
); // [ ['Return-Path:', 'brett@...'], ...]
```

* common

method|params|return|comment
---|---|---|---
UIDL|`{String\|Number}` msgNum|`{Promise}` resolve to `{Array}` list of responsed|msgNum is optional
RETR|`{String\|Number}` msgNum|`{Promise}` resolve to `{String}` or `{Stream}`|Returns stream when `parseStreamToString: false`
TOP|`{String\|Number}` msgNum, `{Number}` n|`{Promise}` resolve to `{String}` or `{Stream}`|`n` defaults to 0; returns stream when `parseStreamToString: false`
CAPA||`{Promise}` resolve to `{Object<String, String[]>}` capability map|Capability names are uppercased keys, values are argument arrays (often empty)
supports|`{String}` capability|`{Promise}` resolve to `{Boolean}`|Trims and uppercases the input name; lazily calls `CAPA` and reuses cached capabilities for subsequent checks
QUIT||`{Promise}` resolve to `{String}` message of response message|

Note that

- `SASL`, `RESP-CODES`, `LOGIN-DELAY`, `PIPELINING`, `EXPIRE`, and `IMPLEMENTATION`
- PLAIN, LOGIN, and DIGEST-MD5

...are capability tokens not commands.

```js
const capabilities = await pop3.CAPA();
console.log(capabilities.CAPA); // []

const hasPipelining = await pop3.supports('pipelining');
console.log(hasPipelining); // true or false
```

## ERROR

pop3 will throw new Error's with an error message from Server.
Beyond that, Error may have two properties attached by pop3.

property|comment
---|---
`err.eventName`|event name comes from `socket.on`. Includes `error`, `close`, `timeout`, `end`, and `bad-server-response`. `command` may also throw `no-socket`.
`err.command`|which command causes the error. For example, `PASS example`

## To-dos

1. Testing:
    1. Set up CI with hidden `pop.config.json` credentials
    1. Avoid skipping some tests
1. Edge cases
    1. After timeout, ensure any stream is ended (so other commands can
        continue)
    1. Ensure `command` will reject if socket is ended.
    1. Ensure in fixing the above that can QUIT and reuse same instance

---
_Source: https://npm.io/package/node-pop3 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._