# wp-config.php constants

> Pin connection credentials, the encryption key and debug switches in wp-config.php instead of the database — every BOOLEAN_SMTP_ and BOOLEANSMTP_ constant BooleanSMTP reads.

Every constant below is read once, when the plugin boots — define it in `wp-config.php`, before
`/* That's all, stop editing! */`. A defined constant always overrides the same value stored in the
database; an empty string never overrides a stored value (`defined('X')` can be true with `''`).

## Connection credentials

A connection's credentials can be pinned outside the database with a constant named
`BOOLEANSMTP_{DRIVER}_{KEY}` — the driver slug, upper-cased, then the connection setting's key,
upper-cased. For example, a SendGrid connection's `api_key` setting becomes:

```php
define( 'BOOLEANSMTP_SENDGRID_API_KEY', 'SG.xxxxxxxx' );
```

The same rule covers every transport's credential fields — `BOOLEANSMTP_MAILGUN_API_KEY`,
`BOOLEANSMTP_POSTMARK_API_KEY`, `BOOLEANSMTP_SMTP_USERNAME` / `BOOLEANSMTP_SMTP_PASSWORD`, and so
on. Use the [wp-config builder](#wp-config-builder) below, or read a transport's exact field names
from `GET /transports/{driver}` on the [REST API](/rest-api/).

Two legacy aliases are still accepted, for sites that already had them defined before the canonical
naming settled:

| Constant | Same as | Driver |
| --- | --- | --- |
| `BOOLEAN_SMTP_USERNAME` (no S after `BOOLEAN`) | `BOOLEANSMTP_SMTP_USERNAME` | Custom SMTP |
| `BOOLEAN_SMTP_PASSWORD` (no S after `BOOLEAN`) | `BOOLEANSMTP_SMTP_PASSWORD` | Custom SMTP |
| `BOOLEANSMTP_MICROSOFT_TOKEN` | `BOOLEANSMTP_OUTLOOK_TOKEN` | Outlook (`refresh_token` / `token`) |

### Amazon SES

SES has its own constant set, since its API and SMTP modes take different fields:

```php
// API mode
define( 'BOOLEANSMTP_AWS_SES_ACCESS_KEY_ID', '...' );   // or BOOLEANSMTP_AWS_ACCESS_KEY_ID
define( 'BOOLEANSMTP_AWS_SES_SECRET_KEY', '...' );       // or BOOLEANSMTP_AWS_SECRET_ACCESS_KEY
define( 'BOOLEANSMTP_AWS_REGION', 'us-east-1' );
define( 'BOOLEANSMTP_AWS_SES_CONFIGURATION_SET', '...' );
define( 'BOOLEANSMTP_AWS_SES_CUSTOM_ENDPOINT', '...' );
define( 'BOOLEANSMTP_AWS_SES_ENABLE_V2_API', true );
define( 'BOOLEANSMTP_AWS_SES_STATIC_TAGS', '...' );

// SMTP mode
define( 'BOOLEANSMTP_AWS_SES_SMTP_USERNAME', '...' );
define( 'BOOLEANSMTP_AWS_SES_SMTP_PASSWORD', '...' );
define( 'BOOLEANSMTP_AWS_SES_SMTP_HOST', '...' );
define( 'BOOLEANSMTP_AWS_SES_SMTP_PORT', 587 );
define( 'BOOLEANSMTP_AWS_SES_SMTP_ENCRYPTION', 'tls' );
define( 'BOOLEANSMTP_AWS_SES_SMTP_REGION', 'us-east-1' );

// IAM role source on EC2 (no keys at all)
define( 'BOOLEANSMTP_AWS_ENABLE_IMDS_ROLE_SOURCE', true );
define( 'BOOLEANSMTP_AWS_EC2_IMDSV2_TOKEN_TTL', 21600 );
```

## OAuth redirects (Google, Microsoft, Zoho)

By default, an OAuth connection flow bounces through a central hosted relay so a customer never has
to register their own redirect URI with the provider. Three constants change that:

| Constant | Effect |
| --- | --- |
| `BOOLEANSMTP_USE_LOCAL_OAUTH_REDIRECTS` | `true` sends the provider straight back to this site's own REST callback instead of the relay. Off by default. |
| `BOOLEANSMTP_GOOGLE_OAUTH_REDIRECT_URI` | Overrides the redirect URI for the Google flow specifically — for a self-registered Google Cloud app. |
| `BOOLEANSMTP_MICROSOFT_OAUTH_REDIRECT_URI` | Same, for Microsoft/Outlook. |
| `BOOLEANSMTP_ZOHO_OAUTH_REDIRECT_URI` | Same, for Zoho. |

A per-provider constant wins over `BOOLEANSMTP_USE_LOCAL_OAUTH_REDIRECTS`, which wins over the
relay; the `boolean_smtp_google_oauth_redirect_uri` / `_microsoft_oauth_redirect_uri` /
`_zoho_oauth_redirect_uri` [filters](/hooks/connections/) can override any of them.

## Behavior

| Constant | Effect |
| --- | --- |
| `BOOLEAN_SMTP_ENCRYPTION_KEY` | A dedicated key for encrypting connection credentials at rest, separate from the WordPress auth salts. **Changing it after credentials are stored makes them unreadable** — export connections first. |
| `BOOLEAN_SMTP_PRESERVE_DATA` | `true` keeps connections, settings and logs in the database when the plugin is deleted, for a later reinstall. |
| `BOOLEAN_SMTP_WP_MAIL_TAKEOVER` | **Read-only.** BooleanSMTP defines this itself, once it confirms it registered `wp_mail()` successfully — check `defined('BOOLEAN_SMTP_WP_MAIL_TAKEOVER')` from your own code to know whether it did. Do not define it yourself. |

<Aside type="caution" title="Key rotation">
	`BOOLEAN_SMTP_ENCRYPTION_KEY` derives the key that encrypts every stored credential. If you change or remove it after
	connections exist, BooleanSMTP can no longer decrypt them. Export connections (or note their credentials) before
	rotating the key, then re-enter them.
</Aside>

## Debug logging

Off by default; every channel is opt-in. See [debug logging](https://docs.booleansmtp.com/troubleshooting/) on the user
site for what each channel captures.

| Constant | Default | Purpose |
| --- | --- | --- |
| `BOOLEAN_SMTP_DEBUG_HTTP` | `false` | Log outgoing HTTP requests (`http_api_debug`). |
| `BOOLEAN_SMTP_DEBUG_QUERIES` | `false` | Append database query summaries at shutdown (needs `SAVEQUERIES`). |
| `BOOLEAN_SMTP_DEBUG_REQUEST` | `false` | Log incoming request metadata. |
| `BOOLEAN_SMTP_DEBUG_MAILER` | `false` | Log payloads from `boolean_smtp_api_debug`. |
| `BOOLEAN_SMTP_DEBUG_SECRET_VISIBILITY` | unset (`mask`) | `mask` (default), `show` (exact values — never on a live site), or `full` (`[REDACTED]`). |
| `BOOLEAN_SMTP_DEBUG_REQUEST_SECRET_VISIBILITY` | `''` (follows global) | Visibility for **REQUEST PAYLOAD** lines only, independent of `HTTP OUT`. |
| `BOOLEAN_SMTP_DEBUG_REDACT` | `false` | Legacy: `true` with no `SECRET_VISIBILITY` set behaves like `full`. |
| `BOOLEAN_SMTP_DEBUG_ATTACH_API_DEBUG` | `false` | Legacy opt-in for raw browser diagnostics; prefer the `boolean_smtp_api_debug_response_enabled` filter. |
| `BOOLEAN_SMTP_DEBUG_LOG_DIR` | `''` | Moves the whole log root (including SMTP debug sessions) to `<dir>/boolean-smtp-logs/`. Empty uses `wp-content/uploads/booleanpress/boolean-smtp/logs`. |

```php
define( 'SAVEQUERIES', true );              // required for BOOLEAN_SMTP_DEBUG_QUERIES
define( 'BOOLEAN_SMTP_DEBUG_HTTP', true );
define( 'BOOLEAN_SMTP_DEBUG_SECRET_VISIBILITY', 'mask' );
```

## Not for wp-config.php

`BOOLEAN_SMTP_FILE`, `BOOLEAN_SMTP_PATH`, `BOOLEAN_SMTP_URL`, `BOOLEAN_SMTP_PLUGIN_FILE`,
`BOOLEAN_SMTP_VERSION`, `BOOLEAN_SMTP_PRO_VERSION` and `BOOLEAN_SMTP_VITE_DEV_SERVER(_URL)` are set
by the plugin itself at boot, for its own internal use. They are documented here only so you
recognize them if you see them in a stack trace or `wp boolean-smtp` output — do not define them.

## wp-config builder

Pick a driver and fill in its credentials; copy the `define()` block it writes. Covers the 5 mailers
released today — the same rule applies to any other transport; see [REST API:
transports](/rest-api/#transports) for its exact field names.

<WpConfigBuilder />

## Next steps

- [REST API](/rest-api/) — `GET /transports/{driver}` returns every field a transport's connection
  settings accept, if you need a field this page does not list.
- [Extending: custom transport](/extending/custom-transport/) — a transport you register yourself
  reads its own credentials however you write it; these constants only apply to the built-in ones.