Skip to content

[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

HookTypeArgumentsNotes
subset_mail_mailerfilter?Mailer $mailer, array $atts, string $sourceThe mailer for one email. Return null for core’s mail(). A mailer that isn’t configured is ignored.
subset_mail_backup_mailerfilter?Mailer $backup, ?Mailer $failed, array $atts, WP_Error $errorThe mailer to try once more when the email’s own mailer fails. null by default, so nothing is retried.
subset_mail_mailersfilterarray $mailers, Settings $settingsEvery 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, with configure( PHPMailer $phpmailer ): void, for a mailer that sets up core’s PHPMailer;
  • ApiMailer, with send( Message $message ): bool|WP_Error, for a mailer that sends by itself. Message holds the parsed email: to, cc, bcc, reply_to, from_email, from_name, subject, body, content_type, charset, headers and attachments.

Register it through subset_mail_mailers. Its id is what the mailer setting stores.

Sending and logging

HookTypeArgumentsNotes
subset_mail_sentactionint $idAfter an email is sent and logged.
subset_mail_failedactionint $id, WP_Error $errorAfter an email fails and is logged. Fires after any backup has had its try.
subset_mail_blockedactionarray $attsFor each email SUBSET_MAIL_DISABLE stops.
subset_mail_loggedactionint $id, string $statusA log entry is complete: sent, failed or blocked. Fires before subset_mail_sent and subset_mail_failed.
subset_mail_backupactionMailer $backup, ?Mailer $failed, WP_Error $errorA backup is about to try an email.
subset_mail_backup_sentactionMailer $backupThe backup sent an email that SMTP or core’s mail() couldn’t.
subset_mail_log_entryfilterarray $row, array $attsThe row before it’s written. Return false to leave the email out of the log.
subset_mail_store_bodyfilterbool $store, array $attsWhether to store this email’s body. Defaults to the Store the content of each email setting.
subset_mail_log_days_maxfilterint $daysThe 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:

HookTypeNotes
subset_mail_admin_tabsfilterarray $tabs, tab slug => label. Empty by default.
subset_mail_admin_panel_{$tab}actionPrints the content of an add-on’s tab.
subset_mail_settings_after_formactionPrints at the end of the Settings tab.
subset_mail_log_after_listactionPrints below the Log tab’s list.
subset_mail_admin_enqueueactionEnqueues an add-on’s scripts and styles on the screen.
subset_mail_menu_statusfilterStatus 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.

ConstantSetting
SUBSET_MAIL_MAILERnone, smtp, ses, postmark, mailgun, sendgrid or brevo
SUBSET_MAIL_FROM_EMAIL, SUBSET_MAIL_FROM_NAME, SUBSET_MAIL_FORCE_FROMThe 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_PASSSMTP. Encryption is tls, ssl or none.
SUBSET_MAIL_SES_KEY, SUBSET_MAIL_SES_SECRET, SUBSET_MAIL_SES_REGIONAmazon SES
SUBSET_MAIL_POSTMARK_TOKENPostmark
SUBSET_MAIL_MAILGUN_KEY, SUBSET_MAIL_MAILGUN_DOMAIN, SUBSET_MAIL_MAILGUN_REGIONMailgun. Region is us or eu.
SUBSET_MAIL_SENDGRID_KEYSendGrid
SUBSET_MAIL_BREVO_KEYBrevo
SUBSET_MAIL_DISABLEStops 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.

RouteMethodNotes
/logGETNewest 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>GETOne entry, with headers and attachments decoded.
/log/<id>DELETEAnswers { deleted, previous }.
/log/<id>/resendPOST409 subset_mail_no_body when the content wasn’t stored.
/testPOSTSends 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.