/emailjs-imap-client

IMAP client for browsers

Primary LanguageJavaScriptMIT LicenseMIT

emailjs-imap-client

IMAP client library written with ES2015 (ES6).

Build Status

StringEncoding API

This module requires TextEncoder and TextDecoder to exist as part of the StringEncoding API (see: MDN whatwg.org). This is supported by Firefox, Chrome and Opera. For other browser environments there is a polyfill.

TCPSocket API

There is a shim that brings Mozilla-flavored version of the Raw Socket API to other platforms.

If you are on a platform that uses forge instead of a native TLS implementation (e.g. chrome.socket), you have to set the .oncert(pemEncodedCertificate) handler that passes the TLS certificate that the server presents. It can be used on a trust-on-first-use basis for subsequent connection.

If forge is used to handle TLS traffic, you may choose to handle the TLS-related load in a Web Worker. Please use tlsWorkerPath to point to tcp-socket-tls-worker.js!

Please take a look at the tcp-socket documentation for more information!

Installation

npm:

npm install emailjs-imap-client

Usage

AMD

Require emailjs-imap-client.js as ImapClient

API

var ImapClient = require('emailjs-imap-client')
var client = new ImapClient(host[, port][, options])

Please note that instances cannot be reused! After terminating a connection or encountering an error, please create a new ImapClient instance!

Where

  • host is to hostname to connect to
  • port (optional) is the port to connect to (defaults to 143)
  • options (optional) is the options object
    • auth is the authentication information object
      • user is the username of the user (also applies to Oauth2)
      • pass is the password of the user
      • xoauth2 is the OAuth2 access token to be used instead of password
    • id (optional) is the identification object for RFC2971 (ex. {name: 'myclient', version: '1'})
    • useSecureTransport (optional) enables TLS
    • ignoreTLS – if set to true, do not call STARTTLS before authentication even if the host advertises support for it
    • requireTLS – if set to true, always use STARTTLS before authentication even if the host does not advertise it. If STARTTLS fails, do not try to authenticate the user
    • enableCompression - if set to true then use IMAP COMPRESS extension (rfc4978) if the server supports it (Gmail does). All data sent and received in this case is compressed with deflate
    • ca (optional) (only in conjunction with the TCPSocket shim) if you use TLS with forge, pin a PEM-encoded certificate as a string. Please refer to the tcp-socket documentation for more information!
    • tlsWorkerPath (optional) (only in conjunction with the TCPSocket shim) if you use TLS with forge, this path indicates where the file for the TLS Web Worker is located. Please refer to the tcp-socket documentation for more information!
    • compressionWorkerPath (optional) offloads de-/compression computation to a web worker, this is the path to the browserified emailjs-imap-client-compressor-worker.js

Default STARTTLS support is opportunistic – if the server advertises STARTTLS capability, the client tries to use it. If STARTTLS is not advertised, the clients sends passwords in the plain. You can use ignoreTLS and requireTLS to change this behavior by explicitly enabling or disabling STARTTLS usage.

Example

var client = new ImapClient('localhost', 143, {
    auth: {
        user: 'testuser',
        pass: 'testpass'
    }
});

Use of web workers with compression: If you use compression, we can spin up a Web Worker to handle the TLS-related computation off the main thread. To do this, you need to browserify emailjs-imap-client-compressor-worker.js, specify the path via options.compressionWorkerPath

client.onerror = function(error){}

Initiate connection

Call client.connect() to establish an IMAP connection:

client.connect().then(() => { /* ready to roll */ });

Close connection

There are two ways to close the connection.

The IMAP way is to send the LOGOUT command with logout().

client.logout().then(() => { /* connection terminated */ });

This method doesn't actually terminate the connection, it sends LOGOUT command to the server, to which the server responds by closing the connection.

The better way is to force-close the connection with close(). This closes the TCP socket and is independent of the network status.

client.close().then(() => { /* connection terminated */ });

List mailboxes

List all mailboxes with listMailboxes() method

client.listMailboxes().then((mailboxes) => { ... })

Mailbox object is with the following structure

  • root (boolean) true if the node is root
  • name (string) unicode decoded name of the mailbox
  • path (string) full path to the mailbox
  • delimiter (string) path delimiting symbol. In the event the server returns NIL for this (some servers do this for the INBOX), it will be coerced to a '/' at this time, but the behavior may be changed in the future depending on how the folder creation API is implemented.
  • listed (boolean) mailbox was found in the LIST response
  • subscribed (boolean) mailbox was found in the LSUB response
  • specialUse (string) mailbox was identified as a special use mailbox ('\Trash', '\Sent', '\Junk' etc. see RFC6154)
  • specialUseFlag (string) the same as specialUse but without using folder name based heuristics
  • flags (array) a list of flags
  • children (array) a list of child mailboxes

Example mailboxes object:

{
  "root": true,
  "children": [
    {
      "name": "INBOX",
      "delimiter": "/",
      "path": "INBOX",
      "children": [],
      "flags": ["\\HasNoChildren"],
      "listed": true,
      "subscribed": true
    },
    {
      "name": "[Gmail]",
      "delimiter": "/",
      "path": "[Gmail]",
      "flags": ["\\Noselect","\\HasChildren"],
      "listed": true,
      "subscribed": true,
      "children": [
        {
          "name": "All Mail",
          "delimiter": "/",
          "path": "[Gmail]/All Mail",
          "children": [],
          "flags": ["\\HasNoChildren","\\All"],
          "listed": true,
          "specialUse": "\\All",
          "specialUseFlag": "\\All",
          "subscribed": true
        }
      ]
    }
  ]
}

Root level INBOX is case insensitive, so all subfolders of INBOX, Inbox etc. are mapped together. The first occurence of INBOX defines the name property for the parent element. path values remain as listed.

For example the following IMAP response lists different INBOX names:

    * LIST () "INBOX"
    * LIST () "Inbox/test"

These different INBOX names are mapped to the following object:

{
  "root": true,
  "children": [
    {
      "name": "INBOX",
      "delimiter": "/",
      "path": "INBOX",
      "children": [
        {
          "name": "test",
          "delimiter": "/",
          "path": "Inbox/test",
        }
      ]
    }
  ]
}

List namespaces

List available namespaces with listNamespaces(). If NAMESPACE extension is not supported, the method is a no-op.

Namespace object is with the following structure

  • personal is an array of namespace elements or false for Personal Namespace
  • users is an array of namespace elements or false for Other Users' Namespace
  • shared is an array of namespace elements or false for Shared Namespace

Namespace element object has the following structure

  • prefix is the prefix string
  • delimiter is the hierarchy delimiter. This can be null for some servers but will usually be a string.

NB! Namespace_Response_Extensions are not supported (extension data is silently skipped)

Namespaces should be checked before attempting to create new mailboxes - most probably creating mailboxes outside personal namespace fails. For example when the personal namespace is prefixed with 'INBOX.' you can create 'INBOX.Sent Mail' but you can't create 'Sent Mail'.

Example:

client.listNamespaces().then((namespaces) => { ... })
{
    "personal": [
        {
            "prefix": "",
            "delimiter": "/"
        }
    ],
    "users": false,
    "shared": false
}

Create mailbox

Create a folder with the given path with createMailbox(path), automatically handling utf-7 encoding. You currently need to manually build the path string yourself.

If the server indicates a failure that the folder already exists, but responds with the ALREADYEXISTS response code, the request will be treated as a success.

Command: CREATE

Example

// On a server with a personal namesapce of INBOX and a delimiter of '/',
// create folder Foo.  Note that folders using a non-empty personal namespace
// may automatically assume the personal namespace.
client.createMailbox('INBOX/Foo').then(() => { ... });

// Do the same on a server where the personal namespace is ''
client.createMailbox('Foo').then(() => { ... });

Select mailbox

Select specific mailbox by path with selectMailbox(path, options)

Where

  • path is the full path to the mailbox (see path property with listMailboxes)
  • options optional options object with the following properties
    • condstore if set to true adds (CONDSTORE) option when selecting
    • readOnly if set to true uses EXAMINE instead of SELECT

Resolves with

  • mailboxInfo is an object with mailbox properties
    • exists (number) the count of messages in the selected mailbox
    • flags (array) an array of flags used in the selected mailbox
    • permanentFlags (array) an array of permanent flags available to use in the selected mailbox
    • readOnly (boolean) true if the mailbox is in read only mode
    • uidValidity (number) UIDValidity value
    • uidNext (number) predicted next UID value
    • highestModseq (string) (with CONDSTORE only) highest modseq value (javascript can't handle 64bit uints so this is a string)

Example

client.selectMailbox('INBOX').then((mailbox) => { ... });
{
    "readOnly": false,
    "exists": 6596,
    "flags": [
        "\\Answered",
        "\\Flagged"
    ],
    "permanentFlags": [
        "\\Answered",
        "\\Flagged"
    ],
    "uidValidity": 2,
    "uidNext": 38361,
    "highestModseq": "3682918"
}

List messages

List messages with listMessages(path, sequence, query[, options])

Where

  • path is the path for the mailbox which should be selected for the command. Selects mailbox prior to executing FETCH if not already selected.
  • sequence defines the range of sequence numbers or UID values (if byUid option is set to true). Example: '1', '1:*', '1,2:3,4' etc.
  • query is an array of keys that need to be fetched. Example: ['uid', 'flags', 'body.peek[headers (date)]']
  • options is an optional options object
    • byUid if true executes UID FETCH instead of FETCH
    • changedSince is the modseq filter. Only messages with higher modseq value will be returned

Resolves with

  • messages is an array of messages from the provided sequence range

A note about sequence ranges: This method does not stream the values, so using * as a range selector might be a really bad idea. If the mailbox contains thousands of messages and you are running a 1:* query, it might choke your application. Additionally, remember that * stands for the sequence number of the last message in the mailbox. This means that if you have 10 messages in a mailbox and you run a query for a range of 5000:* you still get a match as the query is treated as 10:5000 by the server

IMAP Commands: FETCH, CHANGEDSINCE

Example

client.listMessages('1:10', ['uid', 'flags', 'body[]']).then((messages) => {
    messages.forEach((message) => console.log('Flags for ' + message.uid + ': ' + message.flags.join(', ')));
});

Message item

A listed message item includes (but is not limited to), the selected fields from the query argument (all keys are lowercase). Additionally the argument order and even argument names might not match. For example, when requesting for body.peek you get body back instead. Additionally the message includes a special key # which stands for the sequence number of the message.

Most arguments return strings (eg. body[]) and numbers (eg. uid) while flags return an array, envelope and bodystructure return a processed object.

{
    "#": 123,
    "uid": 456,
    "flags": ["\\Seen", "$MyFlag"],
    "envelope": {
        "date": "Fri, 13 Sep 2013 15:01:00 +0300",
        "subject": "hello 4",
        "from": [{"name": "sender name", "address": "sender@example.com"}],
        "to": [{"name": "Receiver name", "address": "receiver@example.com"}],
        "message-id": "<abcde>"
    }
}

Special keys - if a special key is used, eg. BODY.PEEK[HEADER (Date Subject)], the response key is lowercase and in the form how the server responded it, eg. body[header (date subject)]

Envelope object

An envelope includes the following fields (a value is only included in the response if it is set).

  • date is a date (string) of the message
  • subject is the subject of the message
  • from is an array of addresses from the from header
  • sender is an array of addresses from the sender header
  • reply-to is an array of addresses from the reply-to header
  • to is an array of addresses from the to header
  • cc is an array of addresses from the cc header
  • bcc is an array of addresses from the bcc header
  • in-reply-to is the message-id of the message is message is replying to
  • message-id is the message-id of the message

All address fields are in the following format:

[{
    "name": "MIME decoded name",
    "address": "email@address"
}]

Bodystructure object

A bodystructure object includes the following fields (all values are lowercase, unless the value might be case sensitive, eg. Content-Id value):

  • part is the sub-part selector for BODY[x.x.x], eg. '4.1.1' (this value is not set for the root object)
  • type is the Content-Type of the body part
  • parameters is an object defining extra arguments for Content-Type, example: {border: 'abc'}
  • disposition is the Content-Disposition value (without arguments)
  • dispositionParameters is an object defining extra arguments for Content-Disposition, example: {filename: 'foo.gif'}
  • language is an array of language codes (hardly ever used)
  • location is a string for body content URI (hardly ever used)
  • id is the Content-Id value
  • description is the Content-Description value
  • encoding is the Content-Transfer-Encoding value
  • size is the body size in octets
  • lineCount (applies to text/* and message/rfc822) is the count of lines in the body
  • envelope (applies to message/rfc822) is the envelope object of the sub-part
  • md5 is the MD5 hash of the message (hardly ever used)
  • childNodes (applies to multipart/* and message/rfc822) is an array of embedded bodystructure objects

Example

Bodystructure for the following sample message structure:

multipart/mixed
    text/plain
    multipart/alternative
        text/plain

{
    "type": "multipart/mixed",
    "childNodes": [
        {
            "part": "1",
            "type": "text/plain",
            "encoding": "7bit",
            "size": 8,
            "lineCount": 1
        },
        {
            "part": "2",
            "type": "multipart/alternative",
            "childNodes": [
                {
                    "part": "2.1",
                    "type": "text/plain",
                    "encoding": "7bit",
                    "size": 8,
                    "lineCount": 1
                }
            ]
        }
    ]
}

Searching

Search for messages with search(path, query[, options])

Where

  • path is the path for the mailbox which should be selected for the command. Selects mailbox prior to executing SEARCH if not already selected.
  • query defines the search terms, see below
  • options is an optional options object
    • byUid if true executes UID SEARCH instead of SEARCH

Resolves with

* **results** is an array of sorted and unique message sequence numbers or UID numbers that match the specified search query

Queries are composed as objects where keys are search terms and values are term arguments. Only strings, numbers and Date values are used as arguments. If the value is an array, the members of it are processed separately (use this for terms that require multiple params). If the value is a Date, it is converted to the form of '1-Jan-1970'. Subqueries (OR, NOT) are made up of objects.

Command: SEARCH

Examples:

// SEARCH UNSEEN
query = {unseen: true}
// SEARCH KEYWORD 'flagname'
query = {keyword: 'flagname'}
// SEARCH HEADER 'subject' 'hello world'
query = {header: ['subject', 'hello world']};
// SEARCH UNSEEN HEADER 'subject' 'hello world'
query = {unseen: true, header: ['subject', 'hello world']};
// SEARCH OR UNSEEN SEEN
query = {or: {unseen: true, seen: true}};
// SEARCH UNSEEN NOT SEEN
query = {unseen: true, not: {seen: true}}

Example

client.search({unseen: true}, {byUid: true}).then((result) => {
    result.forEach((uid) => console.log('Message ' + uid + ' is unread'));
});

Update flags

Update message flags with setFlags(path, sequence, flags[, options]). This is a wrapper around store()

Where

  • path is the path for the mailbox which should be selected for the command. Selects mailbox prior to executing if not already selected.
  • sequence defines the range of sequence numbers or UID values (if byUid option is set to true). Example: '1', '1:*', '1,2:3,4' etc.
  • flags is an object defining flag updates, see below for details
  • options is an optional options object
    • byUid if true executes UID SEARCH instead of SEARCH
    • silent if true does not return anything. Useful when updating large range of messages at once ('1:*')

Resolves with

* **messages** is an array of messages from the provided sequence range (or empty when `silent:true` option is set). Includes `flags` property and `uid` if `byUid:true` option was used.

Reading flags

You can check the flags for a message or a range of messages with listMessages - use ['flags'] as the query object.

Flag update object

  • { set: arrFlags } for setting flags
  • { add: arrFlags } for adding new flags
  • { remove: arrFlags } for removing specified flags

Where arrFlags is an array containing flag strings, ie. ['\\Seen', '$MyFlag']

client.setFlags('INBOX', {set: ['\\Seen']}).then((messages) => { ... })

client.setFlags('INBOX', {remove: ['\\Seen']}).then((messages) => { ... })

client.setFlags('INBOX', {add: ['\\Seen']}).then((messages) => { ... })

Store Command

The client also allows direct access to the STORE command, but please use setFlags() for convenience. Anyway, store flags or labels with store(path, sequence, action, flags[, options]).

Where

  • path is the path for the mailbox which should be selected for the command. Selects mailbox prior to executing if not already selected.
  • sequence defines the range of sequence numbers or UID values (if byUid option is set to true). Example: '1', '1:*', '1,2:3,4' etc.
  • action is the STORE argument, eg 'FLAGS' for setting flags
  • flags is an array of flags or labels
  • options is an optional options object
    • byUid if true executes UID SEARCH instead of SEARCH
    • silent if true does not return anything. Useful when updating large range of messages at once ('1:*')

Resolves with

  • messages is an array of messages from the provided sequence range (or empty when silent:true option is set). Includes flags property and uid if byUid:true option was used.

Possible actions

  • FLAGS - overwrite message flags with provided ones
  • +FLAGS - add provided flags to message flags
  • -FLAGS - remove provided flags from message flags
  • X-GM-LABELS - GMail-only IMAP extension to overwrite message labels with provided ones
  • +X-GM-LABELS - GMail-only IMAP extension to add provided labels to message labels
  • -X-GM-LABELS - GMail-only IMAP extension to remove provided labels from message labels

Command: STORE

client.store('INBOX', '1:*', '+X-GM-LABELS', ['\\Sent']).then((messages) => { ... }); // adds GMail `\Sent` label to messages

Delete messages

Delete messages with deleteMessages(path, sequence[, options])

Where

  • path is the path for the mailbox which should be selected for the command. Selects mailbox prior to executing if not already selected.
  • sequence defines the range of sequence numbers or UID values (if byUid option is set to true). Example: '1', '1:*', '1,2:3,4' etc.
  • options is an optional options object
    • byUid if true uses UID values instead of sequence numbers to define the range

Resolves when IMAP server completed the command.

If possible (byUid:true is set and UIDPLUS extension is supported by the server) uses UID EXPUNGE otherwise falls back to EXPUNGE to delete the messages – which means that this method might be destructive. If EXPUNGE is used, then any messages with \Deleted flag set are deleted even if these messages are not included in the specified sequence range.

Commands: EXPUNGE, UID EXPUNGE

Example

client.deleteMessages('INBOX', '1:5').then(() => { ... });

Copy messages

Copy messages with copyMessages(sequence, destination[, options])

Where

  • path is the path for the mailbox which should be selected for the command. Selects mailbox prior to executing if not already selected.
  • sequence defines the range of sequence numbers or UID values (if byUid option is set to true). Example: '1', '1:*', '1,2:3,4' etc.
  • destination is the destination folder path. Example: '[Gmail]/Trash'
  • options is an optional options object
    • byUid if true uses UID values instead of sequence numbers to define the range

Resolves with a response text from the server. Not really useful, can be ignored.

Command: COPY

Example

client.copyMessages('INBOX', '1:5', '[Gmail]/Trash').then(() => { ... });

Move messages

Move messages with moveMessages(path, sequence, destination[, options])

Where

  • path is the path for the mailbox which should be selected for the command. Selects mailbox prior to executing if not already selected.
  • sequence defines the range of sequence numbers or UID values (if byUid option is set to true). Example: '1', '1:*', '1,2:3,4' etc.
  • destination is the destination folder path. Example: '[Gmail]/Trash'
  • options is an optional options object
    • byUid if true uses UID values instead of sequence numbers to define the range

Resolves when IMAP server completed the command.

If possible (MOVE extension is supported by the server) uses MOVE or UID MOVE otherwise falls back to COPY + EXPUNGE.

Command: MOVE

Example

client.moveMessages('INBOX', '1:5', '[Gmail]/Trash').then(() => { ... });

Events

Keeping synchronization with your IMAP server

It is recommended to set up some sort of local caching for the messages. Please note that IMAP relies on a mixture of mailbox-unique identifiers (UID) and sequence numbers, so a mapping between both is definitely recommended.

There are two kinds of updates: 1) When something happens in the currently selected mailbox, and 2) when you select a mailbox

Updates for the selected mailbox

Your IMAP server sends you updates when something happens in the mailbox you have currently selected. Message updates can be listened for by setting the onupdate handler. First argument for the callback is the path, the second is the update type, and the third one is the new value.

Example

client.onupdate = function(path, type, value){
    if (type === 'expunge') {
      // untagged EXPUNGE response, e.g. "* EXPUNGE 123"
      // value is the sequence number of the deleted message prior to deletion, so adapt your cache accordingly
    } else if (type === 'exists') {
      // untagged EXISTS response, e.g. "* EXISTS 123"
      // value is new EXISTS message count in the selected mailbox
    } else if (type === 'fetch') {
      // untagged FETCH response, e.g. "* 123 FETCH (FLAGS (\Seen))"
      // add a considerable amount of input tolerance here!
      // probably some flag updates, a message or messages have been altered in some way
      // UID is probably not listed, probably includes only the sequence number `#` and `flags` array
    }
}

Mailbox change notifications

For your everyday tasks, this client doesn't really require you to explicitly select a mailbox, even though having an eye on which mailbox is selected is useful to receive untagged updates. When a mailbox is opened or closed, the onselectmailbox and onclosemailbox handlers are called.

For onselectmailbox handler the first argument is the path of the selected mailbox and the second argument is the mailbox information object (see selectMailbox).

For onclosemailbox handler the argument is the path of the selected mailbox.

Example

client.onselectmailbox = function(path, mailbox){
    console.log('Opened %s with %s messages', path, mailbox.exists);
}

client.onclosemailbox = function(path){
    console.log('Closed %s', path);
}

The IMAP client has several events you can attach to by setting a listener

Handling fatal error event

The invocation of onerror indicates an irrecoverable error. When onerror is fired, the connection is already closed, hence there's no need for further cleanup.

TCP-Socket related events

Should you be using the TCP-Socket shim on a platform that has no native support for TLS, the certificate of the remote host is propagated via the oncert event. The only argument is the PEM-encoded X.501 TLS certificate, however this doesn't include the whole certificate chain.

Get your hands dirty

$ git clone git@github.com:emailjs/emailjs-imap-client.git
$ cd emailjs-imap-client
$ npm install
$ npm test

License

Copyright (c) 2014 Andris Reinman

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.