@turbosmtp/mail

Send email through the TurboSMTP API.

npm install @turbosmtp/mail

Requires Node.js 22+ (uses the global fetch). Authenticate with a TurboSMTP Consumer Key and Secret.

Usage

import { TurboSmtp } from "@turbosmtp/mail";

const mailer = new TurboSmtp({
  key: process.env.TURBOSMTP_KEY!,
  secret: process.env.TURBOSMTP_SECRET!,
  // region: 'eu', // optional, defaults to 'us'
});

const { mid } = await mailer.send({
  from: "Sender <[email protected]>",
  to: ["[email protected]", "[email protected]"],
  subject: "Hello",
  text: "Plain-text body",
  html: "<p>HTML body</p>",
  replyTo: "[email protected]",
  attachments: [{ content: Buffer.from("file contents"), filename: "note.txt", contentType: "text/plain" }],
});

send() resolves with { mid, raw }, where mid is the message id (kept as a string to preserve its full 64-bit precision) and raw is the parsed API response.

On any non-2xx response it rejects with a TurboSmtpError exposing the parsed error shape: status, errorCode and details (authentication failures), errors (an array of field-level validation messages), and the raw response.

Inline images: give an attachment a cid and reference it from the HTML with src="cid:<the-cid>".

Other supported fields: mimeRaw (a raw MIME message that replaces text and html), campaignId (sent as X-campaign-ID), and referenceId (echoed back in the event webhook).