# SMTP (/docs/v/0.6.1/adapters/smtp)
The SMTP adapter speaks the SMTP protocol directly over Node/Bun TCP and TLS sockets — no Nodemailer, no HTTP, no dependency. Point it at PurelyMail, a self-hosted server, or any provider's SMTP endpoint, and register it more than once under different names for multiple routes.
## Configure [#configure]
Get the host, port, TLS mode, and credentials from your SMTP provider.
```ts title="lib/email.ts"
import { createEmailClient } from "@opencoredev/email-sdk";
import { smtp } from "@opencoredev/email-sdk/smtp";
export const email = createEmailClient({
adapters: [
smtp({
host: "smtp.purelymail.com",
port: 587,
auth: {
user: process.env.SMTP_USER!,
pass: process.env.SMTP_PASS!,
},
}),
],
});
```
### TLS and auth semantics [#tls-and-auth-semantics]
With `secure: true` the whole session is TLS. Otherwise the adapter connects in plaintext and upgrades with `STARTTLS` before authenticating whenever `requireTLS` is set or `auth` is present — credentials never travel unencrypted. Authenticating against a server that cannot do TLS requires an explicit `allowInsecureAuth: true`; without it the adapter throws instead of sending the password in the clear.
## Send [#send]
SMTP maps `cc`, `bcc`, `replyTo`, and `headers`. When a message has both `html` and `text`, the adapter builds a `multipart/alternative` MIME body. The generated `Message-ID` header is `<{idempotencyKey}@email-sdk.local>` when the message has an `idempotencyKey` (a random UUID otherwise), and an explicit `Message-ID` in `headers` overrides it — set one yourself if you need a specific domain for threading or deduplication.
```ts
const result = await email.send({
from: "Acme ",
to: "ops@example.com",
cc: "oncall@example.com",
subject: "Disk usage above 90% on db-1",
text: "db-1 is at 92% disk usage.",
html: "db-1 is at 92% disk usage.
",
headers: { "X-Alert-ID": "alert_481" },
});
console.log(result.accepted); // every recipient the server accepted
console.log(result.id); // parsed from the server's "queued as ..." reply, else the idempotency key
```
`rejected` is always empty — a refused recipient fails the SMTP conversation instead, and every transport error surfaces as a retryable `EmailProviderError`, so SMTP plays well with [retries and fallbacks](/docs/v/0.6.1/concepts/fallbacks-and-retries).
The built-in transport does not build attachment MIME parts, and SMTP has no tag or metadata
concept — any of these fields throws an `EmailValidationError` before connecting. See the
[field support matrix](/docs/v/0.6.1/adapters/field-support).
## Multiple SMTP routes [#multiple-smtp-routes]
`name` lets you register the adapter twice and use one route as the [fallback](/docs/v/0.6.1/concepts/fallbacks-and-retries) for the other.
```ts
export const email = createEmailClient({
adapters: [
smtp({
name: "purelymail",
host: "smtp.purelymail.com",
auth: { user: process.env.PURELYMAIL_USER!, pass: process.env.PURELYMAIL_PASS! },
}),
smtp({
name: "backup-smtp",
host: "smtp.backup.example",
auth: { user: process.env.BACKUP_SMTP_USER!, pass: process.env.BACKUP_SMTP_PASS! },
}),
],
defaultAdapter: "purelymail",
fallback: ["backup-smtp"],
});
```
## Verify from the CLI [#verify-from-the-cli]
`doctor` only checks `SMTP_HOST`; the other settings are optional.
```bash
SMTP_HOST=smtp.purelymail.com npx email-sdk doctor --adapter smtp
```
```bash
npx email-sdk send \
--adapter smtp \
--host smtp.purelymail.com \
--port 587 \
--require-tls \
--user hello@acme.com \
--pass "$SMTP_PASS" \
--from "Acme " \
--to user@example.com \
--subject "SMTP smoke test" \
--text "It works" \
--dry-run
```
Each flag falls back to its env var: `--host`/`SMTP_HOST`, `--port`/`SMTP_PORT` (default 587), `--secure`/`SMTP_SECURE`, `--require-tls`/`SMTP_REQUIRE_TLS`, `--allow-insecure-auth`/`SMTP_ALLOW_INSECURE_AUTH`, `--user`/`SMTP_USER`, `--pass`/`SMTP_PASS`. Drop `--dry-run` for one real send — the only check that proves the host, TLS mode, and credentials actually deliver.