infinity.smtp¶

Module: infinity.smtp

The infinity.smtp namespace contains classes for sending messages through SMTP email servers as a client as well as building you own SMTP server.

client¶

You can use the infinity.smtp.client object to connect to an SMTP server and send messages through 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 SMTP server, followed by calls to the other methods. Make sure to call the free() method when finished, to release the memory allocated by the client object.

Example:

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

try {
  myClient.host = 'smtp.gmail.com';
  myClient.port = 465;
  myClient.encryptMode = infinity.smtp.client.encryptMode.sslTls;
  myClient.authMode = infinity.smtp.client.authMode.default;
  myClient.username = 'youraccount@gmail.com';
  myClient.password = 'yourpassword';

  myClient.connect();

  myClient.authenticate();
  myClient.send('mail.eml');

  myClient.disconnect();
} finally {
  myClient.free();
}

mail.eml example:

To: recipientName@domain.com
From: youraccount@gmail.com
Subject: The Subject
X-Sender: youraccount@gmail.com
Content-Type: text/plain; charset=US-ASCII;
 format=flowed
Content-Transfer-Encoding: 7bit

Mailbody text

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 SMTP client establish a connection nonetheless.

authMode¶

Type: infinity.smtp.client.authMode

Gets and sets the authorization mode for the SMTP client to use, according to infinity.smtp.client.authMode

encryptMode¶

Type: infinity.smtp.client.encryptMode

Gets and sets the encryption mode for the SMTP client to use according to infinity.smtp.client.encryptMode

host¶

Type: string

Gets and sets the SMTP server address to connect to.

password¶

Type: string

Gets and sets the password for authorization.

port¶

Type: number

Gets and sets the communication port with the SMTP 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 SMTP 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 SMTP client object instance. Doesn't accept parameters.

Signature:

constructor()

Example:

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

authenticate()¶

Carries out the authentification process with the SMTP server.

Signature:

authenticate(): boolean

Return type: boolean

Example:

myClient.authenticate();

connect()¶

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

Signature:

connect(): void

Example:

myClient.connect();

disconnect()¶

Disconnects from the server.

Signature:

disconnect(): void

Example:

myClient.disconnect();

free()¶

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

Signature:

free(): void

Example:

myClient.free();

sendFile()¶

Sends an email, reading the email data from the specified file.

Signature:

send( fileName: string ): void

Parameters:

• fileName: string

  Filename, relative path (location relative to the folder with the used INFINITY.JS executable file) or absolute path to the file. The file needs to contain an email in RFC822 format. You can use infinity.mail to create an RFC822 string.

Example:

myClient.sendFile('mail.eml');

sendStream()¶

Sends an email, reading the email data from a stream.

Signature:

sendStream( stream: infinity.stream ): void

Parameters:

• stream: infinity.stream

  Stream from which to read the email data. The data needs to be in RFC822 format. You can use infinity.mail to create an RFC822 string.

Example:

myClient.sendStream(myStream);

sendMail()¶

Sends an email, reading the email data from an 'infinity.mail` object.

Signature:

sendMail( mail: infinity.mail ): void

Parameters:

• mail: infinity.mail

  Mail object from which to read the RFC822 data.

Example:

myClient.sendMail(myMail);

verify()¶

Verifies an address or username (sending a VRFY command to the smtp server).

Signature:

verify( username: string ): string

Parameters:

• username: string

  Username or encoded address (an address in angle brackets <...>).

Return type: string

Example:

myClient.verify('username');

server¶

To run an SMTP server using infinity.smtp.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 SMTP server receives the corresponding SMTP command from a client.

Within these scripts, you can access the infinity.smtp.session object, which will be filled with the parameters of the client's SMTP command. You will also use this SMTP 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.smtp');
let myServer = new infinity.smtp.server(...);
myServer.onLogin = 'smtp/login.js';
myServer.onReceive = 'smtp/receive.js';
myServer.start();

Properties

onConnect¶

Type: string

Script filename (relative to the main script) that will handle SMTP connection requests. Within that script, you can access the infinity.smtp.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 SMTP session, so you can access these in the other SMTP command handlers, as well. The only exception is the id property, which will become invalid in the onDisconnect handler.

onDisconnect¶

Type: string

Script filename (relative to the main script) that will handle SMTP disconnects.

onLogin¶

Type: string

Script filename (relative to the main script) that will handle SMTP login requests. Within that script, you can access the infinity.smtp.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

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.

onMailFrom¶

Type: string

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

• address: sender address
• accept: set this to true to accept the sender address, or to false to refuse sending from that address.

onRcptTo¶

Type: string

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

• address: recipient address
• accept: set this to true to accept the recipient address, or to false to refuse sending to that recipient.

onReceive¶

Type: string

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

• msg: RFC822 email message data.
• receive: set to true to signal successful sending of the message to the client, or false to signal that the message has not been sent.

In the onReceive handler, you will get the message to be sent in the infinity.smtp.session.msg property. This will contain an RFC822 string, containing the message headers and contents. You can use infinity.mail to parse the string into an object to handle the sender, recipient, subject, content and attachments of the message.

You need to set the

Methods

constructor()¶

Creates an SMTP server object.

Signature:

constructor( ssl?: boolean, verifyCertificate?: boolean, port?: number, maxConnections?: number, poolSize?: number, minProtocol?: infinity.smtp.server.protocol, maxProtocol?: infinity.smtp.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 SMTP client connections. If this is set to 465, 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.smtp.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.smtp.server.protocol, optional

  Maximum encryption protocl accepted.

Example:

infinity.loadModule('infinity.smtp');
let myServer = new infinity.smtp.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 SMTP server. The server will run as a separate thread, listening to incoming SMTP client connections and running the scripts specified in the on... command handlers.

Signature:

start(): void

Example:

myServer.start();

stop()¶

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

Signature:

stop(): void

Example:

myServer.stop();

infinity.smtp.client¶

infinity.smtp.client.authMode¶

Values:

• none: 0

  No authentication (allow sending messages without authentication).

• default: 1

  Authenticate using the default username and password method.

• sasl: 2

  Authenticate using SASL (Simple Authentication and Security Layer).

Example:

infinity.loadModule('infinity.smtp');
let authMode = infinity.smtp.client.authMode.default;

infinity.smtp.client.encryptMode¶

Values:

• none: 0

  Unencrypted connection.

• sslTls: 1

  SSL/TLS encrypted connection.

Example:

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

infinity.smtp.server¶

infinity.smtp.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.smtp.server');
let protocol = infinity.smtp.server.protocol.tls1_2;

infinity.smtp.session¶

The infinity.smtp.session object will be available in the command handler scripts run by the infinity.smtp.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.

accept¶

Type: boolean

This is a property that you need to set in the onMailFrom and onRcptTo command handlers to either accept or refuse the given address.

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.

received¶

Type: Boolean

Set this property to true or false in the onReceive command handler to notify the client of success or failure.

address¶

Type: string

This property will contain the sender or recipient email address in the onMailFrom and onRcptTo command handlers.

id¶

Type: number

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

ip¶

Type: string

The IP address from which the POP3 client connected.

msg¶

Type: string

In the onReceive command handler, this will contain the RFC822 message data to be sent. You can use infinity.mail to parse this RFC822 string and access the email's addresses, subject, contents and attachments.

password¶

Type: string

The password used to authenticate the SMTP session.

port¶

Type: number

The port used by the SMTP connection with the client.

username¶

Type: string

The username used to authenticate the SMTP session.

disconnect()¶

Disconnnects the current SMTP connection.

Signature:

disconnect(): void