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: 'user@example.com',
  smtpPassword: 'yourPassword'
};

// Async function to create and use a Smartsmtp instance
async function setupSmtp() {
  const smtpInstance = await Smartsmtp.createSmartsmtpWithRelay(smtpOptions);
  
  // 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.

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: 'me@example.com',
    to: 'recipient@example.com',
    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);
}

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: 'me@example.com',
    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, 'recipient@example.com');

  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.

readme.md

@push.rocks/smartsmtp

Issue Reporting and Security