infinity.pop3¶

Module: infinity.pop3

The infinity.pop3 namespace contains classes for accessing POP3 email servers as a client as well as building your own POP3 server.

client¶

You can use the infinity.pop3.client object to access a POP3 server and retrieve messages from it. The first thing you need to do is set the host, port and encryptMode properties to specify how to connect to the server. Then you'll usually need to set the authMode, username and password properties to specify how to authenticate yourself towards the server. You can also set the timeout to limit the time that the client will try to connect to the server.

After setting the properties, you can use the connect() method to establish a connection to the POP3 server, followed by calls to the other methods to list or retrieve messages. Make sure to call the free() nethod when finished, to release the memory allocated by the client object.

Example:

infinity.loadModule('infinity.pop3');
let myClient = new infinity.pop3.client();

try {
  myClient.host = 'pop.gmail.com';
  myClient.port = 995;
  myClient.encryptMode = infinity.pop3.client.encryptMode.sslTls;
  myClient.authMode = infinity.pop3.client.authMode.userPass;
  myClient.username = 'youraccount@gmail.com';
  myClient.password = 'yourpassword';

  myClient.connect();
  console.debug(myClient.list());
  console.debug(myClient.retrieve(1));
  myClient.disconnect();
} finally {
  myClient.free();
}

Properties

allowUnsafeLegacyRenegotiation¶

Type: boolean

Allows the deprecated ssl unsafe legacy renegotiation. This should be avoided and the server's ssl version should be fixed, instead. If that is not possible, then this option can be used to let the POP3 client establish a connection nonetheless.

authMode¶

Type: infinity.pop3.client.authMode

Gets and sets the authorization mode for the POP3 client to use, according to infinity.pop3.client.authMode

encryptMode¶

Type: infinity.pop3.client.encryptMode

Gets and sets the encryption mode for the POP3 client to use according to infinity.pop3.client.encryptMode

host¶

Type: string

Gets and sets the POP3 server address to connect to.

password¶

Type: string

Gets and sets the password for authorization.

port¶

Type: number

Gets and sets the communication port of the POP3 server.

timeout¶

Type: number

Gets and sets the connection timeout in milliseconds.

useLegacyServerConnect¶

Type: boolean

Allows deprecated, unsafe ssl connections. This should be avoided and the server's ssl version should be fixed, instead. If that is not possible, then this option can be used to let the POP3 client establish a connection nonetheless.

useLegacyServerConnect¶

Type: boolean

Allows deprecated, unsafe ssl connections. This should be avoided and the server's ssl version should be fixed, instead. If that is not possible, then this option can be used to let the POP3 client establish a connection nonetheless.

username¶

Type: string

Gets and sets the username for authorization.

verifyServerCertificate¶

Type: boolean

This option will turn on ssl certificate validation, which will result in a connection error if the server's ssl certificate is not valid (e.g. self-signed).

Methods

constructor()¶

Lets you create an INFINITY.JS POP3 client object instance. Doesn't accept parameters.

Signature:

constructor()

Example:

infinity.loadModule('infinity.pop3');
let myClient = new infinity.pop3.client();

connect()¶

Connects to the POP3 server. The initial properties should be set by the time connect() is called.

Signature:

connect(): void

Example:

myClient.connect();

count()¶

Returns the number of new messages on the POP3 server.

Signature:

count(): number

Return type: number

Example:

let newMessagesCount = myClient.count();

delete()¶

Deletes a message from the POP3 server.

Signature:

delete( msgNum: number ): boolean

Parameters:

• msgNum: ``

  The number of the message to delete.

Return type: boolean

Example:

myClient.delete(1);

disconnect()¶

Disconnects from the server.

Signature:

disconnect(): void

Example:

myClient.disconnect();

free()¶

Frees the memory previously occupied by the POP3 client object instance.

Signature:

free(): void

Example:

myClient.free();

list()¶

Returns a infinity.pop3.listArray of new messages on the POP3 server.

Signature:

list( msgNum?: number ): infinity.pop3.listArray

Parameters:

• msgNum: number, optional

  The number of the message for which to return list info. If unspecified, a list of all messages will be returned.

Return type: infinity.pop3.listArray

Example:

let messageList = myClient.list();
console.debug(messageList[0]['size']);

retrieve()¶

Retrieves a message from the server.

Signature:

retrieve( msgNum: number, fileName?: string ): string

Parameters:

• msgNum: number

  The number of the message to retrieve.

• fileName: string, optional

  If a filename is specified, then the message will be saved to that file. The filename can be relative (location relative to the folder with the used INFINITY.JS executable file) or an absolute path.

Return type: string

Example:

let messageText = myClient.retrieve(1);
myClient.retrieve(msgNum, fileName);

size()¶

Returns the size of the specified message in bytes.

Signature:

size( msgNum?: number ): number

Parameters:

• msgNum: number, optional

  The number of the message to examine.

Return type: number

Example:

myClient.size();

top()¶

Retrieves the headers of the specified message.

Signature:

top( msgNum: number, maxLines?: number, fileName?: string ): string

Parameters:

• msgNum: number

  The number of the message to retrieve.

• maxLines: number

  The number of content lines of the message to retrieve (in addition to the message headers).

• fileName: string, optional

  If a filename is specified, then the message headers will be saved to that file. The filename can be relative (location relative to the folder with the used INFINITY.JS executable file) or an absolute path.

Return type: string

Example:

myClient.top(msgNum);
myClient.top(msgNum, fileName);

uidl()¶

Returns a infinity.pop3.uidlArray with unique numbers for each new message, or for the specified message.

Signature:

uidl( msgNum?: number ): infinity.pop3.uidlArray

Parameters:

• msgNum: number, optional

  The number of the message.

Return type: infinity.pop3.uidlArray

Example:

let uidlList = myClient.uidl();

server¶

To run a POP3 server using infinity.pop3.server you need to set script filenames in the server's onConnect, onLogin, etc. properties. These script filenames have to be relative to your main script and these scripts will be called when the POP3 server receives the corresponding POP3 command from a client.

Within these scripts, you can access the infinity.pop3.session object, which will be filled with the parameters of the client's POP3 command. You will also use this POP3 session object to pass back your reply to the client. You can find the specifics per command in the documentation of each on... property.

Example:

infinity.loadModule('infinity.pop3');
let myServer = new infinity.pop3.server(...);
myServer.onLogin = 'pop3/login.js';
myServer.onTop = 'pop3/top.js';
myServer.onRetrieve = 'pop3/retrieve.js';
myServer.onDelete = 'pop3/delete.js';
myServer.onQuit = 'pop3/quit.js';
myServer.start();

Properties

onConnect¶

Type: string

Script filename (relative to the main script) that will handle POP3 connection requests. Within that script, you can access the infinity.pop3.session object, which will contain the following properties:

• id: POP3 session id
• ip: IP address of the connecting POP3 client
• port: port of the POP3 client connection
• disconnect: this is a function that you can call to disconnect the connection.

These properties will remain valid throughout the POP3 session, so you can access these in the other POP3 command handlers, as well. The only exception is the id property, which will become invalid in the onDisconnect handler.

onDelete¶

Type: string

Script filename (relative to the main script) that will handle POP3 delete requests. Within that script, you can access the infinity.pop3.session object, which will contain the same properties described in the onConnect handler, plus the following:

• item: an object containing information about the message to be deleted, with the following properties:
• deleted: false, set this to true to mark the item as deleted and thus signal success to the delete request. Note that the delete request should not directly delete the message, but rather mark it for deletion (as specified in the POP3 protocol). The message will remain marked as deleted throughout the POP3 session (unless the client resets the delete flag) and you need to handle the onQuit request later to actually delete all the messages marked for deletion (as specified in the POP3 protocol).
• id: the message's id
• size: the messages size (in bytes)
• uid: the message's uid

Deleting messages from POP3 works as follows: the client issues a delete request to the server, which will mark the message as deleted. The client can ask the server to reset all delete flags (which the infinity.pop3.server will automatically handle for you - you don't have to write your own command handler for that). When the client sends a quit command to the server, then the server is expected to delete all messages that have been marked as deleted. If the client disconnects without sending a quit command, then no messages should be deleted.

onDisconnect¶

Type: string

Script filename (relative to the main script) that will handle POP3 disconnects. Within that script, you can access the infinity.pop3.session object, which will contain the same properties described in the onConnect handler (except for the id property no longer being valid, because the connection is being disconnected), plus the following:

• items: an array containing message items with the following properties:
• deleted: true if the message has been marked as deleted, false otherwise
• id: the message's id
• size: the messages size (in bytes)
• uid: the message's uid

Note: do not delete messages that have been marked as deleted in the onDisconnect handler. Messages should only be deleted in the onQuit handler (as specified in the POP3 protocol).

onLogin¶

Type: string

Script filename (relative to the main script) that will handle POP3 login requests. Within that script, you can access the infinity.pop3.session object, which will contain the same properties described in the onConnect handler, plus the following:

• username: the username for authentication
• password: the password for authentication
• authenticated: set this to true if the credentials are valid and to false to signal invalid credentials
• items: an array that you need to fill with information about the messages available:
• deleted: true if the message is marked as deleted, false otherwise
• id: the message's id
• size: the messages size (in bytes)
• uid: the message's uid

The username and password properties will remain valid throughout the rest of the POP3 session, in addition to the properties described in the onConnect command handler. You should validate these credentials and set the authenticated property accordingly. If authentication is successful, you will also need to fill the items array and provide information about all the messages that can be retrieved. You can use arbitrary values for the id and uid properties - the POP3 client will use these values when sending commands to your server, so you will get these values in POP3 session data in the other command handlers.

onQuit¶

Type: string

Script filename (relative to the main script) that will handle POP3 quit requests. Within that script, you can access the infinity.pop3.session object, which will contain the same properties described in the onConnect handler, plus the following:

• items: an array containing message items with the following properties:
• deleted: true if the message should now be deleted, false if the message should not be deleted
• id: the message's id
• size: the messages size (in bytes)
• uid: the message's uid

As specified in the POP3 protocol, all messages that have been marked as deleted should actually be deleted when the client sends the quit command. So you need to iterate through the infinity.pop3.session.items array and delete all messages from your storage that are marked as deleted.

onRetrieve¶

Type: string

Script filename (relative to the main script) that will handle POP3 retrieve requests. Within that script, you can access the infinity.pop3.session object, which will contain the same properties described in the onConnect handler, plus the following:

• item: an object containing information about the message to be retrieved, with the following properties:
• deleted: will be true or false, depending on whether the message has been marked for deletion
• id: the message's id
• size: the messages size (in bytes)
• uid: the message's uid
• lines: set this property to the number of lines the message has
• msg: set this to the message data (as a string)

The message data (the infinity.pop3.session.item.msg property) should be a message according to the RFC822 standard. You can use infinity.mail to conveniently create RFC822 messages.

onTop¶

Type: string

Script filename (relative to the main script) that will handle POP3 top requests (requesting the headers and a certain number of lines from the top of the message content). Within that script, you can access the infinity.pop3.session object, which will contain the same properties described in the onConnect handler, plus the following:

• item: an object containing information about the message to be retrieved, with the following properties:
• deleted: will be true or false, depending on whether the message has been marked for deletion
• id: the message's id
• size: the messages size (in bytes)
• uid: the message's uid
• lines: the number of lines of the message that you should be returning (in addition to the message headers)
• msg: set this to the message data (as a string)

The message data (the infinity.pop3.session.item.msg property) should be a message according to the RFC822 standard. You can use infinity.mail to conveniently create RFC822 messages. In contrast to the retrieve command handled in onRetrieve, the top command asks the server to return only the message headers and a specified number of lines from the top of the message (hence the name of the command). Make sure to return only the message headers plus the top infinity.pop3.session.lines lines of the message content in the infinity.pop3.session.msg session property.

Methods

constructor()¶

Creates a POP3 server object.

Signature:

constructor( ssl?: boolean, verifyCertificate?: boolean, port?: number, maxConnections?: number, poolSize?: number, minProtocol?: infinity.pop3.server.protocol, maxProtocol?: infinity.pop3.server.protocol )

Parameters:

• ssl: boolean, optional

  true to accept encrypted connections (using TLS/SSL), false to only accept unencrypted connections (not recommended).

• verifyCertificate: boolean, optional

  true to validate the SSL certificate, false to ignore certificate problems (e.g. when using self-signed certificates).

• port: number, optional

  The port on which to listen for POP3 client connections. If this is set to 995, then the server will use implicit SSL, otherwise it will accept unencrypted connections and handle STARTTLS requests by the client to switch to an encrypted connection automatically.

• maxConnections: number, optional

  Maximum number of simultaneous connections.

• poolSize: number, optional

  Pool size. The server will maintain a pool of connections that will be reused for better performance.

• minProtocol: infinity.pop3.server.protocol, optional

  Minimal encryption protocol accepted. You can use this to refuse client connections that are using old (possibly obsolete) encryption protocols.

• maxProtocol: infinity.pop3.server.protocol, optional

  Maximum encryption protocl accepted.

Example:

infinity.loadModule('infinity.pop3');
let myServer = new infinity.pop3.server();

setCertificate()¶

Sets the SSL certificate for the current server instance using the corresponding files provided in the function parameters.

Signature:

setCertificate(certFile: string, keyFile: string, rootCertFile?: string, verify?: boolean): void;

Parameters:

• certFile: string

  The path to the certificate file to be used.

• keyFile: string

  The path to the the key file to be used.

• rootCertFile: string, optional

  The path to the the root certificate file to be used.

• verify: boolean, optional

  Whether to verify the validity of the certificate.

Example:

myServer.setCertificate('certFile.crt', 'keyFile.key', 'rootCertFile.crt', true);

start()¶

Starts the POP3 server. The server will run as a separate thread, listening to incoming POP3 client connections and running the scripts specified in the on... command handlers.

Signature:

start(): void

Example:

myServer.start();

stop()¶

Stops the POP3 server. The server will close its port and stop listening for POP3 connections.

Signature:

stop(): void

Example:

myServer.stop();

infinity.pop3.client¶

infinity.pop3.client.authMode¶

Values:

• userPass: 0

  Authenticate using username and password.

• apop: 1

  Authenticate using APOP (Authenticated Post Office Protocol).

• sasl: 2

  Authenticate using SASL (Simple Authentication and Security Layer).

Example:

infinity.loadModule('infinity.pop3');
let authMode = infinity.pop3.client.authMode.userPass;

infinity.pop3.client.encryptMode¶

Values:

• none: 0

  Unencrypted connection.

• sslTls: 1

  SSL/TLS encrypted connection.

Example:

infinity.loadModule('infinity.pop3');
let encryptMode = infinity.pop3.client.encryptMode.sslTls;

infinity.pop3.server¶

infinity.pop3.server.protocol¶

Values:

• tls1_0: 2

  TLS 1 encrypted connection.

• tls1_1: 3

  TLS 1.1 encrypted connection.

• tls1_2: 4

  TLS 1.2 encrypted connection.

• tls1_3: 5

  TLS 1.3 encrypted connection.

Example:

infinity.loadModule('infinity.pop3.server');
let protocol = infinity.pop3.server.protocol.tls1_2;

infinity.pop3.session¶

The infinity.pop3.session object will be available in the command handler scripts run by the infinity.pop3.server. The properties will be filled depending on the command handler and some of the properties are used to provide results of the handler to be returned back to the client.

authenticated¶

Type: boolean

In the onLogin command handler, you need to set this property to true or false depending on whether the provided credentials (username and password) are valid.

item¶

Type: {id: number, uid: string, size: number, deleted: boolean, msg: string, lines: number}

This property will be partly filled for command handlers dealing with a specific message item. The properties of this object are:

• id: the message id
• uid: the message uid
• size: the size of the message (in bytes/octets)
• deleted: true if the message has been marked to be deleted, false otherwise
• msg: you need to set this property in the onRetrieve and onTop command handlers. This needs to be a string containing a message in the RFC822 format. You can use infinity.mail to create messages and convert them to a RFC822 string.
• lines: provided in the onTop command handler. This is the requested number of lines from the message's content requested by the client.

items¶

Type: infinity.pop3.itemArray

This is the current list of messages available in this POP3 session.

id¶

Type: number

The POP3 session id. This will remain constant throughout a single POP3 session and will turn invalid on disconnect.

ip¶

Type: string

The IP address from which the POP3 client connected.

password¶

Type: string

The password used to authenticate the POP3 session.

port¶

Type: number

The port used by the POP3 connection with the client.

username¶

Type: string

The username used to authenticate the POP3 session.

disconnect()¶

Disconnnects the current POP3 connection.

Signature:

disconnect(): void

itemArray¶

Extends: Array<{id: number, uid: string, size: number, deleted: boolean}>

An array of POP3 message items.

listArray¶

Extends: Array<{msgNum: number, size: number}>

An array of POP3 message item id and size information.

uidlArray¶

Extends: Array<{msgNum: number, id: string}>

An array of POP3 message id and uid information.