@cull/imap/INTRO.md

A simple, configurable javascript interface exposing mailboxes and messages via IMAP.

# On Email

This library is for reading email -- not sending. Conceptually, accessing email is familiar but if you haven't directly interacted with a mail server before there a few concepts that may be new. This document is for you.

## [IMAP](https://tools.ietf.org/html/rfc3501)

There are two similar protocols for reading email: POP and IMAP. POP would do the trick but is specifically designed so that retrieving email removes them from the mail server. Conversely, IMAP is designed for one or more clients accessing email from a central server where it stays until instructed otherwise. Typically clients will cache what they receive but the mail server, or upstream, remains authoritative.

## Asynchronous Communication

Interaction between client and server consists of a client sending commands (or requests) and the server sending responses. However, communication is asynchronous so the response for a particular command will not be immediate. Other requests can be sent before a response is received and the server may also send unprompted responses at any time.

### [Tags](https://tools.ietf.org/html/rfc3501#section-2.2.1)

Because of the asynchronous nature, commands are prefixed with an arbitrary, unique alphanumeric `tag` so the response may include it for the client to interpret which command the response is applicable to.

## Mailboxes

Email is organized in mailboxes. Mailboxes may be hierarchically organized, typically referenced by a `path` and delimited by `/`, (e.g. `foo/bar`.) There are a few standard mailboxes. Some are special with distinct behaviors and limitations, e.g. `Inbox` is typically where new mail arrives. Other mailboxes may be present or added.

## Email

Email content consists of a header and body. The header may contain numerous key/values, both standard and not. The body of the email may contain simple text or more complex multipart MIME content.

### Identifiers

Email identification is admittedly convoluted. There are two primary means of identifying a particular email: the sequence number and the UID.

#### [Sequence Number](https://tools.ietf.org/html/rfc3501#section-2.3.1.2)

The sequence number is a fluid reference to the numeric ordered position of the message from 1 to the number of messages in the same mailbox.

#### [UID and UIDVALIDITY](https://tools.ietf.org/html/rfc3501#section-2.3.1.1)

The UID is a unique number in the context of a mailbox. Whereas the sequence number may change when other messages in the same mailbox are modified, the UID should not change. Except, it might. Each mailbox also provides a UIDVALIDITY number. If the UIDVALIDITY number changes all prior UID values are considered obsolete. Therefore, the UID must be combined with the mailbox-specific UIDVALIDITY value to achieve its full potential.

### Flags

Every email may contain zero or more flags (typically prefixed with a forward-slash) to signify things like `/Flagged` (i.e. starred), `/Deleted`, `/Seen` and more. Some flags are triggered automatically, e.g. retrieving the body of an email flagging as `/Seen`. Flags can also be added and removed manually.