node-poplib-gowhich

Another POP3 library

The design propose of the library is simplicity. A lot of common tasks with you POP3 mailbox doesn't require knowledge of the eleven POP3 commands. You just want to retrieve some messages from your mailbox and that's all! So here is quick example how to do this with 'node-poplib-gowhich':

var Client = require('node-poplib-gowhich').Client;
var client = new Client({
  hostname: 'pop.mail.ru',
  port:  995,
  tls: true,
  mailparser: true,
  username: 'username',
  password: 'password'
});
client.connect(function() {
  client.retrieveAll(function(err, messages) {
    messages.forEach(function(message) {
      console.log(message.subject);
    });
    client.quit();
  })
})

Also this is a callback-driven and command-queued library instead of poplib So you can run methods in chain, don't think about already running command and get what you want in callback instead of putting somewhere event-listener functions to retrieve data.

Uses the last TLS Api (since crypto.createCredentials is deprecated), so it works only with node.js v.0.12 or later.

Installation

npm install node-poplib-gowhich

Tests

npm test

Constructor properties

When you create new Client object you should pass an object which describes connection properties.

• hostname - string - mailserver hostname
• port - number - port, usually 110 or 995 for TLS connection
• tls - boolean - use TLS encryption
• username - string - mailbox username
• password - string - mailbox password
• mailparser - boolean - use mailparser library to automatically decode messages

Properties

• connected - boolean - connect and login state

Methods

connect(callback)

• callback - function(err)

Connect to the mailserver using hostname and port. Starts TLS connection if tls property is true. Then login into your mailbox using credentials properties username and password.

count(callback)

• callback - function(err, count)

Returns a count of the messages in the mailbox

retrieve(what, callback)

• what - number or array of numbers - message number, or an array of message numbers
• callback - function(err, messages)

Retrieve a message/messages by its number/numbers. If the mailparser argument is true returned messages will be parsed and looks like an objects. Otherwise it will be strings. Notice that results are sparse array with indexes representing message numbers. You can access message with its number like that messages[number] and use all HOF like this messages.map(function(mail, num){ return [num, mail.subject]; }). Or you can represent it like normal array with construction like this: messages.filter(function(a){ return a'; })

retrieveAll(callback)

• callback - function(err, messages)

Retrieve all messages in mailbox. Result is a sparse array starting from 1.

delete(what, callback)

• what - number or array of numbers - message number, or an array of message numbers
• callback - function(err, messages)

Delete a message/messages by its number/numbers. If you delete several messages and get an error for some message, all you delete transaction will be reset.

Note that if your connection to the server is broken at all then the messages will not actually be deleted. You need to cleanly disconnect from the mail server for this to happen.

deleteAll(callback)

• callback - function(err, statuses)

Delete all messages in mailbox.

retrieveAndDeleteAll(callback)

• callback - function(err, messages)

Retrieve and delete all messages in mailbox. Result is a sparse array starting from 1. In a callback function you'll get an error message or an array of retrieved emails. If you get an error for some reason, all you delete transaction will be reset.

list(number, callback)

• number - number (optional) - message number
• callback - function(err, info)

Returns length of a message in octets. If no number passed, list returns an object contains message numbers as a keys and message lengths as a values

quit(callback)

• callback - function(err)

Finish current session and disconnect. All messages marked as deleted after this command will be erased.

Protocol methods

retr(what, callback)

• what - number or string - message number
• callback - function(err, message)

Retrieve full message by its number.

stat(callback)

• what - number or string - message number
• callback - function(err, stat)

Returns an stat object representing the number of messages currently in the mailbox (count property) and the size in bytes (length property).

top(number, linesCount, callback)

• number - number or string - message number
• linesCount - number or string - the number of lines of the message body you would like returned
• callback - function(err)

Retrieve part of the message including headers, or only headers.

dele(number, callback)

• number - number or string - message number
• callback - function(err, response)

Delete a message by its number.