# imap-scan-box

> Scan an IMAP box and emit for each message found.

Latest version **1.0.3** (published 2017-06-09) · VOL license · 0 weekly downloads

## Install

```sh
npm install imap-scan-box
pnpm add imap-scan-box
yarn add imap-scan-box
bun add imap-scan-box
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2017-06-09 |
| First published | 2017-06-08 |
| Weekly downloads | 0 |
| License | VOL |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | saibotsivad |
| Maintainers | saibotsivad |
| Keywords | imap |

## Links

- npm: https://www.npmjs.com/package/imap-scan-box
- Repository: https://github.com/saibotsivad/imap-scan-box
- Homepage: https://github.com/saibotsivad/imap-scan-box#readme
- Issues: https://github.com/saibotsivad/imap-scan-box/issues
- npm.io page: https://npm.io/package/imap-scan-box

## Recent versions

- 1.0.3 (latest) — 2017-06-09
- 1.0.2 — 2017-06-09
- 1.0.1 — 2017-06-09
- 1.0.0 — 2017-06-08

## README

# imap-scan-box

This module takes an instance of the
[imap](https://github.com/mscdex/node-imap) module, and
a box name (also known as a "folder"), and returns
an emitter which emits for each message in the box.

## general use

```js
const Imap = require('imap')
const scanBox = require('imap-scan-box')

const imap = new Imap({
	user: 'me@gmail.com',
	password: 'abc123',
	host: 'imap.gmail.com',
	port: 993,
	tls: true
})

const boxName = 'INBOX'
const range = '1:10' // earliest 10 messages
const fetch = {
	// data to include in message bodies
	bodies: 'HEADER.FIELDS (FROM TO SUBJECT DATE)'
}

// must wait until imap is ready
imap.once('ready', () => {
	const scanner = scanBox(imap, boxName, range, fetch)
	// emitted messages emit the streaming object
	scanner.on('message', ({ stream }) => {
		let body = ''

		message.on('body', (stream, info) => {
			stream.on('data', chunk => body += chunk.toString('utf8'))
		})

		message.once('attributes', attributes => {
			console.log(attributes)
		})

		message.once('end', () => {
			console.log(body)
		})
	})
})
```

### `imap`

The instance of `imap` provided must be instantiated and
have already emitted the `ready` event.

Note also that the imap module does not support opening
multiple boxes at one time. You will need to establish
a single-thread queue to process multiple boxes.

### `boxName`

The name of the box to scan.

### `range` *(string, default `1:*`)*

The range string for which messages to return.

### `fetch` *(object, optional)*

The `fetch` object expected by the imap module.

Default value is:

```js
options.fetch = {
	bodies: 'HEADER.FIELDS (FROM TO SUBJECT DATE)',
	struct: true
}
```

## emitted events

The returned emitter will emit the following events:

### `error` *(object)*

Each error object emitted has the following properties:

* `action` *(string)* The action which caused the error.
* `error` *(object|string)* The thrown error for that action.

The following error actions exist:

* `open`: Opening the IMAP box threw an error.
* `fetch`: Opened the box, but fetching the messages threw an error.
* `error`: Closing the IMAP box after fetching completed threw an error.

### `opened` *(object)*

Emitted after the IMAP box is opened. The emitted object
is the `box` object given by the imap module.

### `closed` *(object)*

Emitted after the IMAP box is closed. The emitted object
is the `box` object given by the imap module.

### `message` *(object)*

Each message found during the `fetch` will be emitted with the
following properties:

* `sequenceNumber` *(integer)*: The sequence number of that fetch.
* `stream` *(stream)*: The message data, as a stream object.

The stream object is the actual streamed message object
as given by the imap module.

### `end`

Emitted after all actions have completed. Either by way
of the box scan completing, or an error occuring which
prevents further scanning.

## license

Published and released under the [VOL](http://veryopenlicense.com).

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