Broodweb SMTP works with the standard wp_mail() function, so any plugin or theme that sends email through WordPress is covered automatically. Nothing needs to change in your code. This page is for developers who want to customise it further.
How it hooks into WordPress
- SMTP, PHP Mail and Sendmail configure WordPress’s built-in PHPMailer on
phpmailer_init(priority 999). - API mailers (SendGrid, Mailgun, Postmark, Brevo) take over on
pre_wp_mail(priority 20) and fire the standardwp_mail_succeeded/wp_mail_failedactions, so other plugins listening to those still work. - The queue, when enabled, captures emails on
pre_wp_mail(priority 10).wp_mail()returnstrueonce the email is queued; the actual result appears in the logs. - From address forcing uses the
wp_mail_fromundwp_mail_from_namefilters.
Actions
bw_smtp_mailer_configured
Fires after the plugin has configured PHPMailer (SMTP, PHP Mail and Sendmail mailers). Use it to change any PHPMailer property.
add_action( 'bw_smtp_mailer_configured', function ( $phpmailer ) {
$phpmailer->addCustomHeader( 'X-Site', 'shop' );
} );
bw_smtp_email_failed
Fires after a failed email has been logged. Receives the WP_Error and the mail data (to, subject, message, headers, attachments).
add_action( 'bw_smtp_email_failed', function ( WP_Error $error, array $mail ) {
error_log( 'Mail to ' . implode( ',', (array) $mail['to'] ) . ' failed: ' . $error->get_error_message() );
}, 10, 2 );
Filters
bw_smtp_bypass_queue
Return true to send a specific email immediately even when the queue is on, for example password resets.
add_filter( 'bw_smtp_bypass_queue', function ( bool $bypass, array $atts ) {
return $bypass || str_contains( (string) $atts['subject'], 'Password Reset' );
}, 10, 2 );
bw_smtp_providers
Add or change entries in the provider list on the settings screen. An SMTP preset needs a label, the smtp engine and a preset:
add_filter( 'bw_smtp_providers', function ( array $providers ) {
$providers['myhost'] = array(
'label' => 'My Host SMTP',
'engine' => 'smtp',
'preset' => array( 'host' => 'mail.myhost.com', 'port' => 587, 'encryption' => 'starttls' ),
'note' => 'Use your cPanel email account password.',
);
return $providers;
} );
bw_smtp_template_variables
Register extra variables for email templates. Keys include the braces.
add_filter( 'bw_smtp_template_variables', function ( array $map ) {
$map['{support_phone}'] = '+1 555 0100';
return $map;
} );
Scheduling an email from code
use BW_SMTP\Queue\Scheduler;
$result = Scheduler::schedule(
array(
'to' => '[email protected]',
'subject' => 'Monthly stock check',
'message' => '<p>Time for the monthly stock check.</p>',
),
'2026-12-01 09:00', // site timezone
'monthly' // none | daily | weekly | monthly | yearly
);
if ( is_wp_error( $result ) ) {
// invalid date or recipient
}
To queue an email for background sending with a priority (1 = highest, 99 = lowest), use BW_SMTP\Queue\Queue::add( $wp_mail_args, $priority ). Check that the class exists before calling it, in case the plugin is deactivated.
REST API
The admin screens use the REST namespace bw-smtp/v1. Every route except /ping requires the manage_options capability and a valid X-WP-Nonce header (or Application Password authentication).
| Route | Method | Purpose |
|---|---|---|
/dashboard |
GET | Dashboard figures |
/settings |
GET, POST | Read or save settings (secrets are never returned) |
/test-connection |
POST | Run the step-by-step connection test |
/test-email |
POST | Send a test email |
/logs, /logs/{id} |
GET | List or read log entries |
/logs/{id}/retry, /logs/delete |
POST | Re-send or delete entries |
/logs/export |
GET | Export logs |
/queue |
GET | Queue rows and counts |
/queue/action |
POST | pause, resume, run_now, retry, delete, clear |
/schedule |
POST | Schedule an email |
/templates, /templates/save, /templates/action |
GET, POST | List, save, duplicate, delete, preview templates |
/analytics |
GET | Analytics for ?days= (7–365) |
/diagnostics |
POST | Run health checks |
/system-status |
GET | Environment report |
/notifications |
GET | Recent notifications |
/export, /import |
POST | Settings and template bundles |
/ping |
GET | Public health check |
Data stored
- One option,
bw_smtp_settings. Passwords and API keys are encrypted (AES-256-CBC with an HMAC, keyed from your WordPress salts). - Tables with your database prefix:
bw_smtp_logs,bw_smtp_queue,bw_smtp_templates,bw_smtp_reports,bw_smtp_notifications,bw_smtp_connections. - Cron events:
bw_smtp_process_queue(every minute),bw_smtp_daily_maintenance,bw_smtp_weekly_report.
All of these are removed when the plugin is deleted from the Plugins screen.