---
title: "Custom SMTP"
description: "Connect any SMTP server to BooleanSMTP with host, port, encryption and authentication, choose where credentials live, and watch the raw SMTP handshake while troubleshooting."
image: "https://booleansmtp.com/docs/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://booleansmtp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom SMTP

import { Steps, Aside } from '@booleanpress/nimbus/components';

**Custom SMTP** connects BooleanSMTP to any SMTP server: your host's own mail server, a provider not
listed elsewhere in Mailers, or an SMTP relay a provider issues you directly.

## Before you begin

From your SMTP provider or host: a **host**, a **port**, whether it needs **encryption**, and, if it
requires authentication, a **username** and **password**.

## Add the connection

1. In your WordPress admin sidebar, go to **BooleanSMTP → Mailers**.
2. Click **Add Connection** and choose **Custom SMTP**.
3. Under **Sender Settings**, fill in **From Email** and **From Name**.
4. Under **SMTP Server Credentials**, fill in **SMTP Host**, **Port** (default `587`), and
   **Encryption Method**: **None**, **SSL**, or **TLS** (default **TLS**). **Auto TLS** sits next to
   it, on by default; see the tip below.
5. Turn on **Authentication** if your server requires a login, then fill in **Username** and
   **SMTP Password**.
6. Choose **Credential Storage**: **Database**, **WP Config**, or **Environment**.
7. Click **Register Connection**.

![The Custom SMTP connection form, with Host, Port, Encryption Method, Auto TLS and Authentication fields.](../../../assets/screenshots/custom-smtp.webp "Custom SMTP connection form")

> **Tip**
>
> **Auto TLS** stays on by default even with **Encryption Method: None**: PHPMailer still tries an
> opportunistic STARTTLS upgrade if your server advertises support for it, so "None" doesn't guarantee
> a fully plaintext connection. Turn **Auto TLS** off only if a server misbehaves when STARTTLS is
> offered but not explicitly requested.

## Choose where credentials are stored

**Credential Storage** offers **Database**, **WP Config**, or **Environment**. Switching away from
**Database** replaces the whole **SMTP Server Credentials** panel with a snippet naming every field
below as a constant, not just the username and password:

```php
define('BOOLEANSMTP_SMTP_HOST', 'mail.example.com');
define('BOOLEANSMTP_SMTP_PORT', 587);
define('BOOLEANSMTP_SMTP_ENCRYPTION', 'tls');
define('BOOLEANSMTP_SMTP_USERNAME', '...');
define('BOOLEANSMTP_SMTP_PASSWORD', '...');
```

As **Environment**, define the same names as OS environment variables instead of PHP constants. See
[Storing credentials in wp-config](/docs/advanced/wp-config-credentials/) for the general naming rule.

> **Note**
>
> Three more constants exist but have no field in the connection form at all, in either storage mode:
> `BOOLEANSMTP_SMTP_TIMEOUT` (seconds, 1 to 300, default 10), `BOOLEANSMTP_SMTP_DEBUG_LEVEL` (0 to 4),
> and `BOOLEANSMTP_SMTP_CLIENT_HOSTNAME` (the name your server announces in EHLO/HELO). They only take
> effect once **Credential Storage** is set to **WP Config** or **Environment**; there's no way to set
> just one of them while leaving the rest in the database. Most sites never need these; **Connection
> Timeout** is the one worth knowing about if sends to a slow host time out before PHPMailer's 10 second
> default gives up.

## Send a test email

Use **Test Email** in the sidebar to confirm the connection works: see
[Send a test email](/docs/getting-started/send-a-test-email/) for the steps.

## Common errors

- **"Connection timeout" or "Network error"**: check your firewall allows outbound SMTP, try the
  other common port (465 for SSL, 587 for TLS), and check with your host for port restrictions.
- **"Authentication failed"**: verify the username and password are correct; some providers require
  an app password rather than your normal account password.
- **A self-signed or internal certificate fails TLS verification**: BooleanSMTP always verifies the
  server's TLS certificate, and there's currently no setting to turn that off. Install a valid
  certificate on the server, or only use **Encryption Method: None** over a trusted private network.
- **See the raw SMTP conversation for a failed send**: turn on **Test Email Activity Console**
  (**BooleanSMTP → Settings → Testing & Content**), then send another **Test Email**; the full SMTP
  handshake for that send appears right on the page.

## Next steps

- [Send a test email](/docs/getting-started/send-a-test-email/)
- [Set a fallback connection](/docs/advanced/fallback-and-retries/)
- [Storing credentials in wp-config](/docs/advanced/wp-config-credentials/)
- [Check delivery in Logs](/docs/logs/)
- [Nothing arrived?](/docs/learn/nothing-arrived/)

Source: https://booleansmtp.com/docs/mailers/smtp/index.mdx