@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
| Option | Required | Notes |
|---|---|---|
smtp | yes | Passed 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. |
from | yes | Default sender. A template may override it. |
logger | no | A notifkit logger. |
limits | no | Send rate, { limit, windowSeconds }. No default, since it depends on your server. Set it to your relay's quota. |
Which template keys it reads
| Template key | Lands as |
|---|---|
subject | The subject line. |
text or body | The plain-text part. |
htmlBody or html | The HTML part. A text-only template gets one built from the escaped text. |
from | Overrides the constructor's sender, for this template only. |
replyTo | Sent 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 happened | Result |
|---|---|
| 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, timeouts | Retried |
Destination isn't one plain address, e.g. Alice <[email protected]> or a comma-separated list | Fails, 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.
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();