---
title: SMTP
description: Connect to an SMTP relay with host, port, and auth.
icon: Truck
source: "src/transports/smtp.ts"
---

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.

<Callout title="The one rule">
  Use `createSMTPMailer` for host/port config; use `createMailer` only with an explicit `SMTPTransport` that already has an adapter.
</Callout>

## Quick start

<Steps>
  <Step title="Create an SMTP mailer">

```ts
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! },
});
```

  </Step>
  <Step title="Send with the channel API">

```ts
await mailer.send({
  from: "hello@example.com",
  to: "person@example.com",
  subject: "Hello",
  text: "Hi",
});
```

  </Step>
</Steps>

## 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 |
| `adapter` | `SocketAdapter` | auto via `createSMTPMailer` |
| `pool` | `boolean` | `false` |
| `dkim` | `DKIMConfig` | optional |

For local capture with defaults and REST helpers, use [Mailpit](./mailpit) or [Inbucket](./inbucket) instead of hand-wiring SMTP ports.

## Troubleshooting

<Accordions>
  <Accordion title="Should I call the provider SDK?">
    No. Use the sently sender; provider-specific extras stay on the transport instance.
  </Accordion>
  <Accordion title="createMailer rejects host and port">
    Pass an explicit transport, or use `createSMTPMailer` for relay configuration.
  </Accordion>
  <Accordion title="Local development without a real relay">
    Use [Mailpit](./mailpit), [Inbucket](./inbucket), or [Preview](/docs/decorators/preview).
  </Accordion>
</Accordions>

## Learn more

- [Mailpit](./mailpit) — local SMTP catcher with inbox API
- [Inbucket](./inbucket) — local SMTP catcher with mailbox REST API
- [Email channel](/docs/channels/email) — `createMailer` / `createSMTPMailer`
- [Runtimes](/docs/get-started/runtimes) — socket adapters

## Next

<Cards>
  <Card title="Mailpit" href="/docs/transports/mailpit" />
  <Card title="Email channel" href="/docs/channels/email" />
  <Card title="Transports" href="/docs/transports" />
</Cards>