[00] Subset Mail, For developers
Developer reference
Subset Mail's actions and filters, adding a mailer, the wp-config.php constants, WP-CLI commands and the REST API, plus what Pro adds.
This page lists everything you can use to work with Subset Mail from code: hooks, constants, WP-CLI commands and the REST API. Every hook name starts with subset_mail_.
How an email is sent
API mailers send from core’s pre_wp_mail filter and return the provider’s result to wp_mail(). SMTP sets up core’s PHPMailer in phpmailer_init, and wp_mail() sends as usual.
Each email gets a log row when it starts (status sending), and the row is updated with the result. Because pre_wp_mail skips core’s wp_mail_succeeded, Subset Mail fires its own subset_mail_sent and subset_mail_failed, and still fires core’s wp_mail_failed with a WP_Error, so other plugins see failures as usual.
The log records who sent each email as its source: plugin:<folder>, mu-plugin:<folder>, theme:<folder> or core, found from the call stack.
Choosing the mailer
| Hook | Type | Arguments | Notes |
|---|---|---|---|
subset_mail_mailer | filter | ?Mailer $mailer, array $atts, string $source | The mailer for one email. Return null for core’s mail(). A mailer that isn’t configured is ignored. |
subset_mail_backup_mailer | filter | ?Mailer $backup, ?Mailer $failed, array $atts, WP_Error $error | The mailer to try once more when the email’s own mailer fails. null by default, so nothing is retried. |
subset_mail_mailers | filter | array $mailers, Settings $settings | Every mailer, keyed by id. Add your own here. |
$atts is the email as wp_mail() received it. subset_mail_mailer is asked more than once per email (by the log, the API sender and PHPMailer’s setup), so give the same answer every time for the same email.
<?php
// Send WooCommerce's email through Postmark, and everything else through the main mailer.
add_filter( 'subset_mail_mailer', function ( $mailer, array $atts, string $source ) {
if ( 'plugin:woocommerce' !== $source ) {
return $mailer;
}
return \Subset\Mail\Plugin::instance()->mailers()->get( 'postmark' ) ?? $mailer;
}, 10, 3 );
When an API mailer fails, a backup sends straight away and wp_mail() returns the backup’s result. When SMTP or core’s mail() fails, only an API backup can try, from wp_mail_failed: the email goes out and the log says sent, but wp_mail() has already returned false.
Adding a mailer
A mailer implements Subset\Mail\Mailers\Mailer (id(), label() and is_configured()) and one of two contracts:
PhpMailerMailer, withconfigure( PHPMailer $phpmailer ): void, for a mailer that sets up core’s PHPMailer;ApiMailer, withsend( Message $message ): bool|WP_Error, for a mailer that sends by itself.Messageholds the parsed email:to,cc,bcc,reply_to,from_email,from_name,subject,body,content_type,charset,headersandattachments.
Register it through subset_mail_mailers. Its id is what the mailer setting stores.
Sending and logging
| Hook | Type | Arguments | Notes |
|---|---|---|---|
subset_mail_sent | action | int $id | After an email is sent and logged. |
subset_mail_failed | action | int $id, WP_Error $error | After an email fails and is logged. Fires after any backup has had its try. |
subset_mail_blocked | action | array $atts | For each email SUBSET_MAIL_DISABLE stops. |
subset_mail_logged | action | int $id, string $status | A log entry is complete: sent, failed or blocked. Fires before subset_mail_sent and subset_mail_failed. |
subset_mail_backup | action | Mailer $backup, ?Mailer $failed, WP_Error $error | A backup is about to try an email. |
subset_mail_backup_sent | action | Mailer $backup | The backup sent an email that SMTP or core’s mail() couldn’t. |
subset_mail_log_entry | filter | array $row, array $atts | The row before it’s written. Return false to leave the email out of the log. |
subset_mail_store_body | filter | bool $store, array $atts | Whether to store this email’s body. Defaults to the Store the content of each email setting. |
subset_mail_log_days_max | filter | int $days | The longest the log can be kept, in days. 90 by default, kept between 1 and 3650. |
<?php
// Never log password reset emails.
add_filter( 'subset_mail_log_entry', function ( $row, array $atts ) {
return str_contains( (string) $atts['subject'], 'Password Reset' ) ? false : $row;
}, 10, 2 );
The log is the table {prefix}subset_mail_log, one per site. Dates are stored in UTC.
Admin screens
An add-on extends Subset → Mail with these hooks:
| Hook | Type | Notes |
|---|---|---|
subset_mail_admin_tabs | filter | array $tabs, tab slug => label. Empty by default. |
subset_mail_admin_panel_{$tab} | action | Prints the content of an add-on’s tab. |
subset_mail_settings_after_form | action | Prints at the end of the Settings tab. |
subset_mail_log_after_list | action | Prints below the Log tab’s list. |
subset_mail_admin_enqueue | action | Enqueues an add-on’s scripts and styles on the screen. |
subset_mail_menu_status | filter | Status badges shown for Subset Mail on the Subset overview. |
An add-on attaches on subset_mail_loading, which fires before any of the plugin’s components register.
Constants
Set these in wp-config.php. A setting set by a constant is locked on the settings screen. Every setting has one, named SUBSET_MAIL_ plus the setting’s name in capitals, so the log’s limits are SUBSET_MAIL_LOG_DAYS and SUBSET_MAIL_LOG_MAX_ROWS.
| Constant | Setting |
|---|---|
SUBSET_MAIL_MAILER | none, smtp, ses, postmark, mailgun, sendgrid or brevo |
SUBSET_MAIL_FROM_EMAIL, SUBSET_MAIL_FROM_NAME, SUBSET_MAIL_FORCE_FROM | The From address and name, and whether to replace one another plugin set |
SUBSET_MAIL_SMTP_HOST, SUBSET_MAIL_SMTP_PORT, SUBSET_MAIL_SMTP_ENCRYPTION, SUBSET_MAIL_SMTP_USER, SUBSET_MAIL_SMTP_PASS | SMTP. Encryption is tls, ssl or none. |
SUBSET_MAIL_SES_KEY, SUBSET_MAIL_SES_SECRET, SUBSET_MAIL_SES_REGION | Amazon SES |
SUBSET_MAIL_POSTMARK_TOKEN | Postmark |
SUBSET_MAIL_MAILGUN_KEY, SUBSET_MAIL_MAILGUN_DOMAIN, SUBSET_MAIL_MAILGUN_REGION | Mailgun. Region is us or eu. |
SUBSET_MAIL_SENDGRID_KEY | SendGrid |
SUBSET_MAIL_BREVO_KEY | Brevo |
SUBSET_MAIL_DISABLE | Stops all sending. Stopped emails are logged as blocked. |
WP-CLI
Under the shared wp subset group:
wp subset mail test you@example.com # exits with status 1 when it isn't sent
wp subset mail log list --status=failed --since=2026-10-01
wp subset mail log get 42 --format=json
wp subset mail log resend 42 # needs the stored body
wp subset mail log list --status=failed --format=ids | xargs wp subset mail log delete
wp subset mail log prune # run the daily prune now
wp subset mail settings set from_email shop@example.com
log list takes --status, --search, --since, --limit, --fields and --format, newest first, with dates in UTC. settings has list, get, set and reset. Passwords and API keys aren’t settings, so set them on the screen or by constant. On multisite, settings set saves the mailer and its connection settings to the network’s settings and says so.
REST API
The namespace is subset-mail/v1. Every route needs manage_options: a logged-in cookie with an X-WP-Nonce, or an application password.
| Route | Method | Notes |
|---|---|---|
/log | GET | Newest first. Filters status, search and since, paged by page and per_page (at most 100), with X-WP-Total and X-WP-TotalPages. |
/log/<id> | GET | One entry, with headers and attachments decoded. |
/log/<id> | DELETE | Answers { deleted, previous }. |
/log/<id>/resend | POST | 409 subset_mail_no_body when the content wasn’t stored. |
/test | POST | Sends a test email to to. |
A send that fails is 500 subset_mail_not_sent with the mailer’s error. A send stopped by SUBSET_MAIL_DISABLE is 409 subset_mail_disabled. A missing entry is 404 subset_mail_not_found.
What Pro adds
Subset Mail Pro is built on the hooks above: its backup connection answers subset_mail_backup_mailer, its routing rules answer subset_mail_mailer, alerts listen on subset_mail_failed, log forwarding on subset_mail_logged, and longer retention raises subset_mail_log_days_max to 365. Its commands join wp subset mail:
wp subset mail routes list
wp subset mail routes add source woocommerce postmark # from, to-domain or source
wp subset mail routes test --to=customer@example.com --source=woocommerce
wp subset mail alerts test
wp subset mail forwarding test
wp subset mail log export --status=failed > failed.csv
wp subset mail log export --network # every site's log, on multisite
Its settings can be locked with constants too: SUBSET_MAIL_PRO_BACKUP_MAILER, SUBSET_MAIL_PRO_ALERT_EMAIL, SUBSET_MAIL_PRO_ALERT_WEBHOOK, SUBSET_MAIL_PRO_ALERTS_PER_HOUR, SUBSET_MAIL_PRO_FORWARD_WEBHOOK and SUBSET_MAIL_PRO_FORWARD_SYSLOG.