Star
Packages

@notifkit/provider-smtp

Email over plain SMTP, built on nodemailer. Works with any SMTP server: a self-hosted Postfix, Gmail, or the SMTP endpoint of SES, SendGrid, Postmark, Mailgun or Brevo.

npm install @notifkit/provider-smtp
import { NotifkitServer } from "notifkit";
import { SmtpTransport } from "@notifkit/provider-smtp";

const smtp = new SmtpTransport({
  smtp: {
    host: "smtp.example.com",
    port: 587,
    auth: { user: process.env.SMTP_USER!, pass: process.env.SMTP_PASS! },
    pool: true,
  },
  from: "Acme <[email protected]>",
});

const server = new NotifkitServer({
  services: ["all"],
  providers: [smtp],
});

A recipient's email contact target is the destination, so it holds their address:

await notifkit.addContact("usr_123", { channel: "email", target: "[email protected]" });

Options

OptionRequiredNotes
smtpyesPassed to nodemailer's createTransport, with 10 s timeouts unless you set your own: host, port, secure, auth, TLS settings, and pool: true to reuse connections. A URL such as smtps://user:[email protected] works too.
fromyesDefault sender. A template may override it.
loggernoA notifkit logger.
limitsnoSend rate, { limit, windowSeconds }. No default, since it depends on your server. Set it to your relay's quota.

Which template keys it reads

Template keyLands as
subjectThe subject line.
text or bodyThe plain-text part.
htmlBody or htmlThe HTML part. A text-only template gets one built from the escaped text.
fromOverrides the constructor's sender, for this template only.
replyToSent only when present.

The List-Unsubscribe headers notifkit adds to topic mail are passed through.

Failures and retries

nodemailer reports the server's SMTP reply code, and the transport decides from it:

What happenedResult
Permanent rejection (5xx, such as 550 mailbox unavailable or 535 bad credentials)Fails, no retry
Temporary rejection (4xx, such as 451 greylisting), 503, connection errors, timeoutsRetried
Destination isn't one plain address, e.g. Alice <[email protected]> or a comma-separated listFails, no retry, nothing sent

Connecting, the greeting and each socket wait time out after 10 seconds, to match notifkit's default send timeout. nodemailer's own defaults run to minutes. To change them, set connectionTimeout, greetingTimeout or socketTimeout in smtp, or in the URL's query.

No idempotency, no webhooks

SMTP has no idempotency key: if the server accepts a message but its reply is lost, the retry sends it again. SMTP has no delivery webhooks either, so a bounce that arrives later as an email isn't reported to notifkit. For engagement tracking and bounce suppression, use provider-resend.

Shutting down

From notifkit 0.1.20, server.stop() closes the transport after delivery stops. On older versions a pool's open connections keep Node running, so call close() yourself:

await server.stop();
smtp.close();