smtp-connection

What is smtp-connection?

The smtp-connection npm package is a low-level module for handling SMTP (Simple Mail Transfer Protocol) connections. It allows you to connect to an SMTP server, authenticate, and send emails. This package is useful for developers who need fine-grained control over the SMTP communication process.

What are smtp-connection's main functionalities?

Connecting to an SMTP Server

This feature allows you to establish a connection to an SMTP server. You can specify the host, port, and whether to use a secure connection.

const SMTPConnection = require('smtp-connection');
const connection = new SMTPConnection({
  host: 'smtp.example.com',
  port: 587,
  secure: false
});
connection.connect(function(err) {
  if (err) {
    console.error('Connection error:', err);
  } else {
    console.log('Connected to SMTP server');
  }
});

Authenticating with the SMTP Server

This feature allows you to authenticate with the SMTP server using a username and password.

connection.login({
  user: 'username',
  pass: 'password'
}, function(err) {
  if (err) {
    console.error('Authentication error:', err);
  } else {
    console.log('Authenticated successfully');
  }
});

Sending an Email

This feature allows you to send an email through the connected and authenticated SMTP server. You can specify the sender, recipient, subject, and body of the email.

const message = {
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Test Email',
  text: 'Hello, this is a test email.'
};
connection.send({
  from: message.from,
  to: message.to
}, message, function(err, info) {
  if (err) {
    console.error('Send error:', err);
  } else {
    console.log('Email sent:', info);
  }
});

Other packages similar to smtp-connection

nodemailer

Nodemailer is a higher-level module for sending emails using various transport methods, including SMTP. It provides a simpler API and more features out of the box compared to smtp-connection, such as support for HTML content, attachments, and various authentication methods.

emailjs

EmailJS is another package for sending emails via SMTP. It offers a straightforward API and supports features like attachments and HTML content. It is similar to Nodemailer but with a slightly different API design.

smtp-client

SMTP-Client is a low-level SMTP client similar to smtp-connection. It provides fine-grained control over the SMTP communication process but with a different API design. It is suitable for developers who need detailed control over the SMTP protocol.

README

smtp-connection

SMTP client module. Connect to SMTP servers and send mail with it.

This module is the successor for the client part of the (now deprecated) SMTP module simplesmtp. For matching SMTP server see smtp-server.

Usage

Install with npm

npm install smtp-connection

Require in your script

var SMTPConnection = require('smtp-connection');

Create SMTPConnection instance

var connection = new SMTPConnection(options);

Where

• options defines connection data
  • options.port is the port to connect to (defaults to 25 or 465)
  • options.host is the hostname or IP address to connect to (defaults to 'localhost')
  • options.secure defines if the connection should use SSL (if true) or not (if false)
  • options.ignoreTLS turns off STARTTLS support if true
  • options.requireTLS forces the client to use STARTTLS. Returns an error if upgrading the connection is not possible or fails.
  • options.name optional hostname of the client, used for identifying to the server
  • options.localAddress is the local interface to bind to for network connections
  • options.connectionTimeout how many milliseconds to wait for the connection to establish
  • options.greetingTimeout how many milliseconds to wait for the greeting after connection is established
  • options.socketTimeout how many milliseconds of inactivity to allow
  • options.debug if true, the connection emits all traffic between client and server as 'log' events
  • options.authMethod defines preferred authentication method, e.g. 'PLAIN'
  • options.tls defines additional options to be passed to the socket constructor, e.g. {rejectUnauthorized: true}
  • options.socket - existing socket to use instead of creating a new one

Events

SMTPConnection instances are event emitters with the following events

• 'error' (err) emitted when an error occurs. Connection is closed automatically in this case.
• 'connect' emitted when the connection is established
• 'end' when the instance is destroyed
• 'log' (data) emitted for all traffic when debug option is set to true

connect

Establish the connection

connection.connect(callback)

Where

• callback is the function to run once the connection is established. The function is added as a listener to the 'connect' event.

After the connect event the connection has the following properties:

• connection.secure - if true then the connection uses a TLS socket, otherwise it is using a cleartext socket. Connection can start out as cleartext but if available (or requireTLS is set to true) connection upgrade is tried

login

If the server requires authentication you can login with

connection.login(auth, callback)

Where

• auth is the authentication object
  • auth.user is the username
  • auth.pass is the password for the user
  • auth.xoauth2 is the OAuth2 access token (preferred if both pass and xoauth2 values are set) or an XOAuth2 token generator object.
• callback is the callback to run once the authentication is finished. Callback has the following arguments
  • err and error object if authentication failed

If a XOAuth2 token generator is used as the value for auth.xoauth2 then you do not need to set auth.user. XOAuth2 generator generates required accessToken itself if it is missing or expired. In this case if the authentication fails, a new token is requeested and the authentication is retried. If it still fails, an error is returned.

XOAuth2 Example

var generator = require('xoauth2').createXOAuth2Generator({
    user: '{username}',
    clientId: '{Client ID}',
    clientSecret: '{Client Secret}',
    refreshToken: '{refresh-token}'
});

// listen for token updates
// you probably want to store these to a db
generator.on('token', function(token){
    console.log('New token for %s: %s', token.user, token.accessToken);
});

// login
connection.login({
    xoauth2: generator
}, callback);

send

Once the connection is authenticated (or just after connection is established if authentication is not required), you can send mail with

connection.send(envelope, message, callback)

Where

• envelope is the envelope object to use
  • envelope.from is the sender address
  • envelope.to is the recipient address or an array of addresses
• message is either a String, Buffer or a Stream. All newlines are converted to \r\n and all dots are escaped automatically, no need to convert anything before.
• callback is the callback to run once the sending is finished or failed. Callback has the following arguments
  • err and error object if sending failed
    • code string code identifying the error, for example 'EAUTH' is returned when authentication fails
    • response is the last response received from the server (if the error is caused by an error response from the server)
    • responseCode is the numeric response code of the response string (if available)
  • info information object about accepted and rejected recipients
    • accepted and array of accepted recipient addresses
    • rejected and array of rejected recipient addresses
    • response is the last response received from the server

quit

Use it for graceful disconnect

connection.quit();

close

Use it for less graceful disconnect

connection.close();

License

MIT

Changelog

v1.2.0 2015-03-09

• Connection object has a new property secure that indicates if the current connection is using a secure TLS socket or not
  • Fixed requireTLS where the connection was established insecurely if STARTTLS failed, now it returns an error as it should if STARTTLS fails