SMTP2GO Node API Wrapper

A library for sending email and accessing the SMTP2GO API from Node.js, browsers, and Web Workers.

Installation

npm i smtp2go-nodejs

Node.js

The package supports both ESM and CommonJS.

ESM

import SMTP2GOApi from "smtp2go-nodejs";

CommonJS

const { default: SMTP2GOApi } = require("smtp2go-nodejs");

Send an email

import SMTP2GOApi from "smtp2go-nodejs";
import { fileURLToPath } from "url";
import { dirname, resolve } from "path";

const __dirname = dirname(fileURLToPath(import.meta.url));
const api = SMTP2GOApi(process.env.APIKEY);

const mail = api.mail()
  .to({ email: "[email protected]", name: "Recipient" })
  .from({ email: "[email protected]", name: "Sender" })
  .subject("Hello!")
  .html("<h1>Hello World</h1>")
  .text("Hello World");

const result = await api.client().consume(mail);
console.log(result);

Attachments and inline images

const mail = api.mail()
  .to({ email: "[email protected]" })
  .from({ email: "[email protected]" })
  .subject("Check this out")
  .html('<h1>Hello</h1><img src="cid:my-image" />')
  .attach(resolve(__dirname, "./report.pdf"))
  .inline("my-image", resolve(__dirname, "./image.jpg"));

await api.client().consume(mail);

Multiple attachments can be passed as an array:

mail.attach([
  resolve(__dirname, "./file1.pdf"),
  resolve(__dirname, "./file2.pdf"),
]);

CC, BCC, and custom headers

const mail = api.mail()
  .to({ email: "[email protected]" })
  .cc({ email: "[email protected]" })
  .bcc([{ email: "[email protected]" }, { email: "[email protected]" }])
  .from({ email: "[email protected]" })
  .subject("Hello")
  .html("<p>Hello</p>")
  .headers({ header: "Reply-To", value: "[email protected]" });

await api.client().consume(mail);

Send using a template

const mail = api.mail()
  .to({ email: "[email protected]", name: "Recipient" })
  .from({ email: "[email protected]", name: "Sender" })
  .subject("Welcome!")
  .template(
    "your-template-id",
    new Map([
      ["username", "Steve"],
      ["action_url", "https://example.com/confirm"],
    ])
  );

await api.client().consume(mail);

Error handling

import SMTP2GOApi, { SMTP2GOError } from "smtp2go-nodejs";

try {
  const result = await api.client().consume(mail);
  console.log(result);
} catch (err) {
  if (err instanceof SMTP2GOError) {
    console.error(`API error ${err.status}:`, err.response);
  } else {
    throw err;
  }
}

Access other API endpoints

const service = api.service("stats/email_bounces", new Map([["days", "7"]]));
const result = await api.client().consume(service);

Browser / Web Worker

The package ships a separate browser build that uses the Web File API instead of Node's fs module. Bundlers (Vite, webpack, etc.) will resolve to it automatically via the browser field in package.json.

Web Worker

// worker.js
import SMTP2GOApi from "smtp2go-nodejs";

self.onmessage = async (event) => {
  const { apiKey, to, from, subject, html, file } = event.data;

  const api = SMTP2GOApi(apiKey);

  try {
    const mail = api.mail()
      .to(to)
      .from(from)
      .subject(subject)
      .html(html);

    // file is a File object transferred from the main thread
    if (file) {
      mail.attach(file);
    }

    const result = await api.client().consume(mail);
    self.postMessage({ success: true, result });
  } catch (err) {
    self.postMessage({ success: false, error: err.message });
  }
};

// main.js — spawning the worker and passing a File from a form input
const worker = new Worker(new URL("./worker.js", import.meta.url), {
  type: "module",
});

const fileInput = document.querySelector('input[type="file"]');

worker.postMessage({
  apiKey: "your-api-key",
  to: { email: "[email protected]" },
  from: { email: "[email protected]" },
  subject: "Hello from a worker",
  html: "<p>Sent from a Web Worker!</p>",
  file: fileInput.files[0],
});

worker.onmessage = ({ data }) => {
  if (data.success) {
    console.log("Sent:", data.result);
  } else {
    console.error("Failed:", data.error);
  }
};

Inline images in the browser

Pass a File object and a content ID (CID), then reference the CID in your HTML:

const mail = api.mail()
  .to({ email: "[email protected]" })
  .from({ email: "[email protected]" })
  .subject("Look at this")
  .html('<img src="cid:my-photo" />')
  .inline("my-photo", imageFileObject);

await api.client().consume(mail);