[00] Subset Mail, User guide
Getting started
Install Subset Mail, choose a mailer, keep its keys in wp-config.php, send a test email and read the email log.
Subset Mail sends your site’s email through SMTP or your email provider’s API instead of PHP’s mail(), and logs every message. This page gets you from install to your first logged email.
There are no ads, upsell screens or admin notices. If an email fails, you’ll find it in Tools → Site Health and in the log.
Install
- Download the free Subset Mail zip from subsetwp.com/download/mail.
- In WordPress, go to Plugins → Add New → Upload Plugin, choose the zip and click Install Now.
- Click Activate.
Subset Mail needs WordPress 6.5 or later and PHP 8.1 or later. Until you choose a mailer, email keeps going out through PHP’s mail() as before, and the log starts recording straight away.
Choose a mailer
Open Subset → Mail → Settings and pick a mailer:
| Mailer | What it needs |
|---|---|
| SMTP | Host, port, encryption (TLS, SSL or none), user, password |
| Amazon SES | Access key, secret key and region |
| Postmark | Server token |
| Mailgun | API key, sending domain and region (US or EU) |
| SendGrid | API key |
| Brevo | API key |
The five API mailers send over HTTPS, so they work on hosts that block SMTP ports. A mailer that’s chosen but not filled in isn’t used: email goes out through PHP’s mail(), and Site Health says so.
Under the mailer, set the From address and From name. By default they’re only used when the plugin sending an email leaves them blank. Tick Use this From address and name even when a plugin sets its own to use them for every email.
Keep keys in wp-config.php
Every setting can be set in wp-config.php instead of the database, and a setting set there shows as locked on the settings screen. Do this for passwords and API keys if you can, so they don’t travel with a database export:
define( 'SUBSET_MAIL_POSTMARK_TOKEN', 'your-server-token' );
The developer reference lists every constant. Keys saved on the settings screen are encrypted with a key derived from your site’s auth salt. If you change your salts, enter the keys again. Site Health tells you when a saved key can’t be read.
Send a test email
Below the settings on Subset → Mail → Settings, enter an address and click Send test email. If it isn’t sent, the mailer’s error is shown on the screen and in the log. You can do the same from the command line:
wp subset mail test you@example.com
Read the log
Subset → Mail → Log lists every email: recipients, subject, mailer, status, the error if it failed, and when it was sent. Filter it by status, or search the recipients and subject. Open an entry to see its headers and attachments, which are listed by name and size and never stored.
Message bodies aren’t stored unless you tick Store the content of each email in the settings, for example while you debug. Resend only works for an email whose body was stored.
Entries older than 30 days are deleted daily, and so are the oldest entries beyond 50,000. Change both with Keep entries for and Keep at most in the settings. Entries can be kept for up to 90 days. Personal data exports and erasure requests include the log, matched on the recipient’s address.
Watch Site Health
Subset Mail adds these checks to Tools → Site Health:
- Recent email failures: any send that failed in the last 24 hours, with the error and a link to the log.
- How email is sent: which mailer is in use, or that a chosen mailer isn’t set up yet.
- Email passwords and API keys: whether every saved key can still be read.
- SPF and DMARC for the From domain: whether your sending domain has both records, and what’s missing. The lookup runs only when you open Site Health.
- Email from a non-production site: a warning on staging and development copies that they’re sending real email.
Stop email from a staging copy
Add this to the staging site’s wp-config.php:
define( 'SUBSET_MAIL_DISABLE', true );
Every email is then stopped before it’s sent and listed in the log as Blocked. Sending is never switched off for you, so remove the line before a copy goes live.
Coming from another mail plugin
Subset Mail can import the mailer settings from WP Mail SMTP, FluentSMTP and Post SMTP. The import is at the end of Subset → Mail → Settings. Their settings are read from the database, so the other plugin doesn’t have to be active, and you see what will be imported before anything is saved.
Send a test email after importing, then deactivate the other plugin. Two mail plugins at once compete to send each email.
Multisite
Network activation sets up every site. The mailer and its connection are set once, under Network Admin → Settings → Subset Mail. The network sets a default From address, which each site can replace with its own, and each site keeps its own log.
Removing the plugin
Deleting the plugin keeps your settings and log, so reinstalling it picks up where you left off. To remove everything when the plugin is deleted, tick Delete all data on uninstall in the settings first. On multisite, each site decides for itself.
Subset Mail Pro
Subset Mail Pro is a separate add-on that needs the free plugin active. It adds tabs to Subset → Mail for:
- a backup connection that retries an email through a second mailer when the first one fails;
- routing rules that send some email through a different mailer, by From address, recipient domain or the plugin that sent it;
- failure alerts by email or webhook;
- forwarding each log entry to a webhook or syslog;
- keeping the log for up to a year, and exporting it as CSV;
- a log of every site in the network admin, on multisite.
Paste your licence key on its License tab. When the licence expires, every feature keeps working and only updates stop. See activate a licence for more.
What to read next
The developer reference covers the hooks, the constants, WP-CLI and the REST API.