SMTP
Connect to an SMTP relay with host, port, and auth.
Connect to an SMTP relay for production or a local catcher.
Prefer createSMTPMailer when your config starts with host and port — it picks a runtime adapter for you.
The one rule
Use createSMTPMailer for host/port config; use createMailer only with an explicit SMTPTransport that already has an adapter.
Quick start
import { createSMTPMailer } from "sently/smtp";
const mailer = await createSMTPMailer({
host: "smtp.example.com",
port: 587,
auth: { user: "you@example.com", pass: process.env.SMTP_PASSWORD! },
});await mailer.send({
from: "hello@example.com",
to: "person@example.com",
subject: "Hello",
text: "Hi",
});Configuration
| Option | Type | Default or requirement |
|---|---|---|
host | string | required |
port | number | 587, or 465 when secure |
secure | boolean | false |
auth | SMTPAuth | optional |
requireTLS | boolean | true when auth is set |
starttls | "required" | "opportunistic" | "never" | opportunistic |
clientName | string | OS hostname, else [127.0.0.1] |
connectionTimeout | number | 30000 ms on Node and Bun; 0 disables |
greetingTimeout | number | connectionTimeout when set, else 30000; 0 disables |
socketTimeout | number | connectionTimeout when set, else 60000; 0 disables |
sendTimeout | number | unset; 0 disables the whole-send deadline |
attachmentBasePath | string | unset; path is trusted local I/O |
adapter | SocketAdapter | auto via createSMTPMailer |
pool | boolean | false |
dkim | DKIMConfig | optional |
For local capture with defaults and REST helpers, use Mailpit or Inbucket instead of hand-wiring SMTP ports.
Troubleshooting
No. Use the sently sender; provider-specific extras stay on the transport instance.
Pass an explicit transport, or use createSMTPMailer for relay configuration.
starttls: "required" fails with TLS_FAILED before AUTH or MAIL. The default opportunistic sends in cleartext only when the server does not advertise STARTTLS, and requireTLS still refuses AUTH on that connection.
Greeting, reply, and STARTTLS handshake deadlines are enforced. A silent server, or a 220 that never completes the TLS handshake, makes send() reject with TIMEOUT. Set greetingTimeout or socketTimeout to 0 only when you accept an unbounded wait.
Learn more
- Mailpit — local SMTP catcher with inbox API
- Inbucket — local SMTP catcher with mailbox REST API
- Email channel —
createMailer/createSMTPMailer - Runtimes — socket adapters