@push.rocks/smartsmtp

A native TypeScript SMTP and sendmail transport with verified TLS, OAuth2, raw-message delivery, streaming attachments, and explicit delivery outcomes.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

To install @push.rocks/smartsmtp, use pnpm:

pnpm add @push.rocks/smartsmtp

Ensure that you are installing the package in a project set up with TypeScript and support for ECMAScript modules, as the usage examples provided will rely on this configuration.

Usage

@push.rocks/smartsmtp simplifies SMTP-based email sending in Node.js applications with a native TypeScript SMTP client and optional template-based emails via @push.rocks/smartmail. This guide walks you through setting up a Smartsmtp instance and sending emails.

Setting Up

First, ensure you import the necessary classes from the module. Here's how you set up your imports using ESM syntax:

import { Smartsmtp } from '@push.rocks/smartsmtp';

Creating SMTP Transport

@push.rocks/smartsmtp provides two primary ways to set up an SMTP transporter: through direct SMTP server credentials or utilizing the local sendmail command.

SMTP Server Credentials

To connect to an SMTP server directly, you'll need the server address, username, and password. Here's how you can create a Smartsmtp instance using SMTP server credentials:

// Define your SMTP configuration
const smtpOptions = {
  smtpServer: 'smtp.example.com',
  smtpPort: 587,
  smtpTlsMode: 'starttls',
  smtpUser: '[email protected]',
  smtpPassword: 'yourPassword'
};

// Async function to create and use a Smartsmtp instance
async function setupSmtp() {
const smtpInstance = await Smartsmtp.createSmartsmtpWithRelay(smtpOptions);

  // Performs greeting, TLS negotiation, and authentication without sending.
  await smtpInstance.verifyConnection();

  // smtpInstance is now ready to use
}

smtpTlsMode supports implicitTls, starttls, and plain. If omitted, implicitTls is used with port 465 to preserve the default relay behavior. For STARTTLS submission services, set smtpPort: 587 and smtpTlsMode: 'starttls'. The plain mode sends directly without upgrading the connection to TLS.

The secure relay contract is marked by SMARTSMTP_SECURE_RELAY_API_VERSION = 1. Consumers that can resolve more than one smartsmtp version at runtime should check this exported marker before relying on TLS-mode selection, trusted CA/server-name options, XOAUTH2, raw streaming, or typed delivery outcomes.

TLS certificate verification is always enabled. When connecting to an IP address, smtpTlsServername can provide the certificate hostname. Private PKI deployments can provide their trusted CA certificates through smtpTlsCa without disabling verification.

OAuth2 / XOAUTH2

The same relay factory accepts an OAuth2 access token instead of a password. The client authenticates with SASL XOAUTH2, as supported by Gmail and Microsoft 365 SMTP submission. Exactly one of smtpPassword and smtpAccessToken must be provided.

const smtpInstance = await Smartsmtp.createSmartsmtpWithRelay({
  smtpServer: 'smtp.example.com',
  smtpPort: 587,
  smtpTlsMode: 'starttls',
  smtpUser: '[email protected]',
  smtpAccessToken: 'current-oauth2-access-token',
});

OAuth2 authentication is rejected for plain transports so bearer tokens are never sent without TLS. Access-token acquisition and refresh remain the caller's responsibility; create the relay with a current access token before sending.

Using Sendmail

If you wish to use the local sendmail command, which is common in UNIX environments, you can create a Smartsmtp instance dedicated to that:

async function setupSendmail() {
  const sendmailInstance = await Smartsmtp.createSmartsmtpSendmail();
  
  // sendmailInstance is now ready to use for sending emails
}

Sending Emails

With a Smartsmtp instance ready, you can send emails directly with sendMail(). The direct API supports from, to, cc, bcc, subject, text, html, custom headers, and file attachments.

async function sendEmail(smtpInstance: Smartsmtp) {
  const result = await smtpInstance.sendMail({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Test Email',
    text: 'This is a test email sent using @push.rocks/smartsmtp.',
    html: '<p>This is a test email sent using @push.rocks/smartsmtp.</p>',
    attachments: [
      {
        filename: 'hello.txt',
        contentType: 'text/plain',
        content: 'hello from smartsmtp',
      },
    ],
  });

  console.log(result.accepted);
}

Attachment content may also be a one-shot Iterable<Uint8Array>, AsyncIterable<Uint8Array>, or Web ReadableStream<Uint8Array>. Streamed attachments require expectedSizeBytes; SmartSMTP verifies the exact source byte count while incrementally base64-encoding with 76-character MIME lines. The message is not assembled in memory. In-memory strings and Uint8Array values remain supported without an explicit size.

const result = await smtpInstance.sendMail({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Streamed report',
  attachments: [{
    filename: 'report.pdf',
    contentType: 'application/pdf',
    content: reportReadableStream,
    expectedSizeBytes: reportSize,
  }],
});

Use sendRaw() when another component already rendered the RFC 822 message. The SMTP envelope is explicit and independent from visible From and To headers. Raw strings, byte arrays, async byte iterables, and Web readable streams are transported byte-for-byte apart from SMTP dot-stuffing and the required DATA terminator.

const result = await smtpInstance.sendRaw({
  rawMessage: renderedMessageStream,
  expectedSizeBytes: renderedMessageSize,
  envelope: {
    mailFrom: '[email protected]',
    rcptTo: ['[email protected]'],
  },
});

When a server advertises the SMTP SIZE extension, known message sizes are sent on MAIL FROM and rejected before DATA if they exceed the advertised limit. SmartSmtpDeliveryError exposes disposition and phase for safe retry decisions: notAccepted proves the DATA terminator was not accepted, while uncertain means the terminator write began or the client lost the final acceptance response. Explicit negative SMTP responses remain notAccepted and include their response code and command through SmartSmtpResponseError.

For template-style messages, create a Smartmail instance from the @push.rocks/smartmail package and send it with sendSmartMail().

import { Smartmail } from '@push.rocks/smartmail';

async function sendSmartEmail(smtpInstance: Smartsmtp) {
  // Create a Smartmail instance
  const myEmail = new Smartmail({
    from: '[email protected]',
    subject: 'Test Email',
    body: 'This is a test email sent using @push.rocks/smartsmtp.'
  });

  // Use the smtpInstance to send the email
  const result = await smtpInstance.sendSmartMail(myEmail, '[email protected]');

  console.log(result); // Check the result
}

In the example above, Smartmail defines the reusable message content. The sendSmartMail() method takes that email configuration, alongside recipient details, and performs the sending operation.

This completes the basic usage guide for @push.rocks/smartsmtp. With these steps, you can integrate straightforward SMTP email sending capabilities into your Node.js applications, leveraging modern TypeScript syntax and ESM modules. For template-based messages, use @push.rocks/smartmail with sendSmartMail().

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.