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: 'sender@example.com',
to: 'recipient@example.com',
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.
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
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
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
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}'
});
generator.on('token', function(token){
console.log('New token for %s: %s', token.user, token.accessToken);
});
connection.login({
xoauth2: generator
}, callback);
Login using NTLM
smtp-connection
has experimental support for NTLM authentication. You can try it out like this:
connection.login({
domain: 'windows-domain',
workstation: 'windows-workstation',
user: 'user@somedomain.com',
pass: 'pass'
}, callback);
I do not have access to an actual server that supports NTLM authentication so this feature is untested and should be used carefully.
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
-
envelope.use8BitMime if true
then inform the server that this message might contain bytes outside 7bit ascii range
-
envelope.dsn is the dsn options
- envelope.dsn.ret return either the full message 'FULL' or only headers 'HDRS'
- envelope.dsn.envid sender's 'envelope identifier' for tracking
- envelope.dsn.notify when to send a DSN. Multiple options are OK - array or comma delimited. NEVER must appear by itself. Available options: 'NEVER', 'SUCCESS', 'FAILURE', 'DELAY'
- envelope.dsn.orcpt original recipient
-
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
quit
Use it for graceful disconnect
connection.quit();
close
Use it for less graceful disconnect
connection.close();
reset
Use it to reset current session (invokes RSET command)
connection.reset(callback);
License
MIT