Nodemailer transport

The whole change

import nodemailer from 'nodemailer'

const transporter = nodemailer.createTransport({
  host: 'smtp.sendgrid.net',
  port: 587,
  auth: { user: 'apikey', pass: process.env.SENDGRID_KEY },
})

// …and several hundred sendMail() calls, elsewhere.

@posthaste/nodemailer is a Nodemailer transport plugin that wraps the TypeScript SDK. It has one dependency — the SDK — and it does not import Nodemailer itself, so it adds nothing to your lockfile that Nodemailer was not already in.

npm i @posthaste/nodemailer

Requires Node 22 or newer, and Nodemailer 6 or newer. ESM only. The from address must be on one of your verified domains, exactly as it must for a direct API send.

await transporter.sendMail({
  from: 'Acme <[email protected]>',
  to: '[email protected]',
  subject: 'Invoice 2026-114',
  text: 'Your invoice is attached.',
  html: '<p>Your invoice is attached.</p>',
  attachments: [
    { filename: 'invoice.pdf', path: './invoices/2026-114.pdf' },
  ],
})

When to use this instead of the SMTP relay

Posthaste already runs an SMTP relay, and Nodemailer can point at it today with no new package at all. That is a perfectly good answer, and for a long-running server on a network that allows outbound SMTP it is often the simpler one — so here is the honest comparison rather than a pitch.

What maps, what changes, what is refused

Nodemailer’s mail.data is a rich, loosely-typed shape; the send API is narrower. Every option lands in one of three buckets, and the governing rule is that nothing is dropped in silence — a team that migrates and does not notice their Bcc stopped arriving is the outcome this design exists to prevent. So an option that cannot be honoured is a synchronous error naming the field, never a quiet omission.

Mapped, unchanged

Mapped, with something changed

Each of these produces a mapping warning: it appears on info.posthaste.mappingWarnings and is passed to the transport’s onWarning hook, so you find out on the first send rather than in a support ticket.

Refused

These throw before anything is sent. The error names the field and says what to do instead. All of them are things that could not be honoured and would change what the recipient receives if they were ignored.

Seeing the warnings

The mapping warnings are on every info, but the useful place to read them is a hook, because that is what fires on the first send rather than whenever somebody next inspects a result. The transport never writes to your process’s output on its own.

const transporter = nodemailer.createTransport(
  posthasteTransport({
    apiKey: process.env.POSTHASTE_API_KEY,
    onWarning: (w) => logger.warn({ field: w.field, code: w.code }, w.message),
  }),
)

What sendMail returns

The fields Nodemailer callers already destructure are all present and mean what they mean for the SMTP transport, plus one addition for everything Nodemailer has no field for.

const info = await transporter.sendMail({ … })

info.messageId   // 'msg_AZLm3kQ8T2Sf9pXbNc7HrQ' — the Posthaste id
info.accepted    // ['[email protected]']
info.rejected    // [] — suppressed recipients land here
info.response    // '202 2.0.0 Accepted: msg_AZLm… queued for 1 recipient'
info.envelope    // { from: '[email protected]', to: [...] }

info.posthaste   // everything Nodemailer has no field for:
//   .id .status .duplicate .scheduledAt .groupId
//   .emails            per-recipient outcome on a fan-out
//   .suppressed        who was skipped, and why
//   .warnings          pre-send lint findings
//   .mappingWarnings   what this transport had to change

info.messageId is the Posthaste message id, not an RFC 5322 Message-ID: the latter is composed server-side at delivery, and it is the Posthaste id that every webhook, log line and waybill is keyed by.

A suppressed recipient appears in info.rejected, where an existing if (info.rejected.length) branch already looks for it. When the only recipient is suppressed there is nothing to accept, and that is an error rather than an empty accepted — the same asymmetry SMTP has.

The fields Nodemailer has no word for

Anything the send API offers that Nodemailer does not goes under a single posthaste key. It is additive: an application that has never heard of it sends exactly what it always sent.

await transporter.sendMail({
  from: 'Acme <[email protected]>',
  to: '[email protected]',
  subject: 'Invoice 2026-114',
  text: 'Your invoice is attached.',

  // Everything the API offers that Nodemailer has no word for.
  posthaste: {
    stream: 'transactional',
    tags: ['invoice'],
    metadata: { invoiceId: '2026-114' },
    idempotencyKey: 'invoice-2026-114',
    scheduledAt: '2026-09-01T09:00:00Z',
  },
})

Stored templates work the same way, and are the one case where a message legitimately has no text and no html.

await transporter.sendMail({
  from: 'Acme <[email protected]>',
  to: '[email protected]',
  // No text and no html: the stored template supplies both.
  posthaste: {
    template: 'invoice-issued',
    variables: { name: 'Ada', amount: '£42.00' },
  },
})

The same keys can be set once on the transport as posthasteTransport({ apiKey, posthaste: { stream: … } }), where a per-message value overrides them.

Errors

Every failure arrives as a PosthasteTransportError, which is deliberately two things at once. It carries code, responseCode and response, so the catch blocks you wrote against the SMTP transport keep working unchanged. And it carries the whole typed Posthaste rejection — the type, the evidence, the retry-after — so new code can branch on something better than a number.

import { isPosthasteTransportError } from '@posthaste/nodemailer'

try {
  await transporter.sendMail(message)
} catch (err) {
  // Existing code keeps working — these are the fields it already reads.
  err.code          // 'EENVELOPE'
  err.responseCode  // 550
  err.response      // '550 suppressed: [email protected] is suppressed'

  if (!isPosthasteTransportError(err)) throw err

  // New code gets something better than a number.
  if (err.type === 'suppressed') {
    const { address, reason } = err.body.error   // 'complaint' — never retry
    await stopMailing(address, reason)
  }

  if (err.type === 'content_blocked') {
    // Every finding, warnings included, so one fix pass covers everything.
    console.error(err.body.error.check, err.body.error.findings)
  }

  if (err.transient) {
    await retryAfter(err.retryAfterSeconds ?? 60)
  }
}

The mapping from a Posthaste error type to an SMTP-shaped code is chosen so that the 4xx/5xx split is correct: every retry loop ever written against SMTP treats 4xx as “come back later” and 5xx as “never send this again”.

verify()

transporter.verify() makes a real authenticated request rather than a reachability ping, so a true from it is a claim worth having: the base URL answers, the key exists and is not revoked, and it holds the emails:send scope.

// Throws unless the key exists, is not revoked, AND holds emails:send.
await transporter.verify()

The scope check is the part that earns the call. A key without emails:send authenticates perfectly and then fails every send with a 403; a verify() that returned true for it would be answering “does this key exist” while you were asking “can I send mail”.

TypeScript

Your existing sendMail calls typecheck unchanged — they are ordinary Mail.Options, and that is the drop-in claim. Only the two additive surfaces need help, for a reason worth stating plainly: @types/nodemailer does not let any transport type its own additions.

• Mail.Options cannot be augmented. It lives inside a declare namespace Mail in a module that ends export = Mail, so a declare module 'nodemailer/lib/mailer' block adds to the module’s export scope rather than to that namespace. All three spellings compile happily and augment nothing.
• createTransport<T>(transport: Transport<T>) returns Transporter<SMTPTransport.SentMessageInfo> — the inferred T is discarded. Every custom transport in the ecosystem gets the SMTP transport’s info type back whatever it really returns.

So the package exports two helpers. Both are optional, both are erased at runtime, and JavaScript users never need either.

import { posthasteMessage, posthasteInfo } from '@posthaste/nodemailer'

const info = posthasteInfo(
  await transporter.sendMail(
    posthasteMessage({ from, to, subject, text }, { tags: ['receipt'] }),
  ),
)

info.posthaste.duplicate   // typed