Skip to content

agsh/yapople

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

yapople

Yet another POP3 library

Coverage Status NPM version

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 'yapople':

const { Client } = require('yapople');
const client = new Client({
  host: 'pop.mail.ru',
  port:  995,
  tls: true,
  mailparser: true,
  username: 'username',
  password: 'password',
  options: {
    secureContext: {
      passphrase: "passphrase"
    }
  }
});
(async () => {
    await client.connect();
    const messages = await client.retrieveAll();
    messages.forEach((message) => {
      console.log(message.subject);
    });
    await client.quit();
})().catch(console.error);

Or with the old callback style:

var Client = require('yapople').Client;
var client = new Client({
  host: 'pop.mail.ru',
  port:  995,
  tls: true,
  mailparser: true,
  username: 'username',
  password: 'password',
  options: {
    secureContext: {
      passphrase: "passphrase"
    }
  }
});
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. You can add connection options (optional) after callback.

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 yapople

Tests

npm test

Constructor properties

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

  • host or hostname - string - mailserver hostname
  • port - number - port, usually 110 or 995 for TLS connection
  • username - string - mailbox username
  • password - string - mailbox password
  • mailparser - boolean - use mailparser library to automatically decode messages
  • tls - boolean - use TLS encryption
  • options - object - Optional configuration JSON object for socket creation. (see. TLS and NET)

Properties

  • connected - boolean - connect and login state

Methods

All the methods can be used both callback-style or promise-style if callback has been omitted. In the examples below only async-await style will be used.

connect([options], [callback])

  • options - object
  • 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.

If options is defined, valuse from options will be used to connect for tls.connect or net.createConnection functions. Precedence goes to them instead of constructor options.

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(a => 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])

disconnect([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.

Changelog

0.4.0

  • all methods returns promises
  • tests were rewritten in js and jest
  • additional parameter options in the constructor and connect method