@sunposs/server-smtp-mailer

Reusable Node SMTP sender for workflow server projects.

Positioning

• Scope: Node server only.
• Distribution: publish as a public npm package; consuming projects should depend on a version range, not copy this directory.
• Responsibility: SMTP connection, TLS/STARTTLS, AUTH LOGIN, envelope commands, dot-stuffing, and UTF-8 text message headers.
• Non-goals: project-specific email templates, verification-code state machines, password-reset rules, user records, secrets, or provider-specific APIs.

Install

pnpm add @sunposs/server-smtp-mailer

Local file: usage is only a pre-publish validation path and should be replaced by a public npm version before cross-project reuse.

Public API

• createSmtpMailer(config): create a reusable mailer.
• mailer.isConfigured(): true when config.host exists.
• mailer.send(input): send a raw MIME message or a simple text email.
• buildTextEmailMessage(input): build a UTF-8 text/plain MIME message.
• encodeHeader, encodeAddressHeader, getEmailAddress: small helpers for business mailers.

timeoutMs applies to connection setup and idle SMTP response waits. Socket errors, close events, and timeouts reject pending SMTP reads so consumers do not need a second business-layer timeout wrapper.

Example

import { buildTextEmailMessage, createSmtpMailer } from "@sunposs/server-smtp-mailer";

const mailer = createSmtpMailer({
  host: env.smtpHost,
  port: env.smtpPort,
  secure: env.smtpSecure,
  startTls: env.smtpStartTls,
  user: env.smtpUser,
  pass: env.smtpPass,
  from: env.smtpFrom,
  heloName: "project.local"
});

const message = buildTextEmailMessage({
  from: env.smtpFrom,
  to: email,
  subject: "Verification code",
  body: `Code: ${code}`
});

await mailer.send({ to: email, message });

Validation

• Run npm test.
• Run npm pack --dry-run from this package directory before publishing.
• Typecheck the consuming server.
• Exercise a local request with missing SMTP and expect a clear failure or dev-code fallback.
• Exercise a real SMTP smoke only with ignored local env or production env files.