sirius-press/docs/smtp.md

# Sending real email

Sirius Press does not disable `wp_mail()`. Contact forms, order receipts,
newsletters and every other reason a site has to send a human an email still
work — you just have to configure a way to send them, exactly as you would on
any WordPress site that is not running on a shared host with a mail server
already attached.

What the fork removes is email as an *identity*. What it leaves alone is email
as a *feature*. Those are different things, and conflating them is how people
end up believing the fork is more restrictive than it is.

---

## What happens without SMTP

Mail to your site's own `.invalid` placeholder addresses never reaches a mail
transport at all. It goes to the Sirius Press inbox — **Inbox** in the admin
menu — where the account holder reads it while signed in. Password-reset
attempts, comment-moderation notices and update nags all land there.

Mail to a real address is handed to PHP's `mail()`. In the Docker stack there
is no mail transport in the container, so it fails. That is the same failure
stock WordPress has in the same situation, reported the same way.

---

## Setting up SMTP

Any of the usual plugins work, because `wp_mail()` is untouched: WP Mail SMTP,
Post SMTP, FluentSMTP. Install one, point it at a provider, done.

Without a plugin, the `phpmailer_init` hook is enough:

```php
// wp-content/mu-plugins/smtp.php
add_action( 'phpmailer_init', function ( $mailer ) {
	$mailer->isSMTP();
	$mailer->Host       = 'smtp.example.net';
	$mailer->Port       = 587;
	$mailer->SMTPAuth   = true;
	$mailer->SMTPSecure = 'tls';
	$mailer->Username   = 'postmaster@example.net';
	// Keep the secret in wp-config.php, not here, so it stays out of backups
	// that include wp-content.
	$mailer->Password   = defined( 'SMTP_PASSWORD' ) ? SMTP_PASSWORD : '';
	$mailer->From       = 'hello@example.net';
	$mailer->FromName   = get_bloginfo( 'name' );
} );
```

A must-use plugin rather than a theme function: it should survive a theme
change, and it should not be editable from the plugin editor in wp-admin.

---

## Choosing a From address

The one thing that will not work is sending *from* a `.invalid` address. Most
providers reject it outright, and the ones that do not will have every message
binned for failing SPF.

So a site that sends mail needs one real domain, for outbound only. This is
slightly awkward for a project whose point is not depending on the DNS system,
and worth being honest about: if your site sends email, you have a dependency
on somebody's DNS, and no amount of BCNR changes that. Email is a DNS protocol.

Two ways to live with it:

- **Accept it, narrowly.** Register a domain used for nothing but outbound mail.
  It has no bearing on how readers reach your site, and if it disappears you
  lose contact-form delivery rather than your site.
- **Avoid sending.** Use the inbox for anything addressed to an account holder,
  and for contact forms use a plugin that stores submissions in the database
  and shows them in wp-admin instead of mailing them. For most small sites this
  is better anyway: you read submissions where you already are, and there is no
  provider to pay or be cut off by.

The second is what a Sirius Press site does by default if you never configure
anything, which is deliberate.

---

## Checking it works

Send yourself something:

```bash
wp eval 'var_dump( wp_mail( "you@example.net", "Sirius Press test", "It sends." ) );'
```

`true` means PHPMailer accepted it, not that it arrived. If it returns `true`
and nothing turns up, the problem is between your provider and the recipient —
SPF, DKIM or a spam filter — and is no longer anything to do with this fork.

To confirm the placeholder interception is working, mail one of your own
accounts. It should return `true`, nothing should leave the server, and the
message should be sitting in that account's inbox.