Using WordPress ‘pre_wp_mail’ PHP filter

by

The ‘pre_wp_mail’ filter is used to override the default behavior of WordPress’s wp_mail() function. By returning a non-null value, you can short-circuit wp_mail() and use that value instead. A boolean return value should be used to indicate whether the email was successfully sent.

Usage

add_filter( 'pre_wp_mail', 'custom_pre_wp_mail', 10, 2 );
function custom_pre_wp_mail( $return, $atts ) {
    // Your custom code here
}

Parameters

  • $return (null|bool): The short-circuit return value.
  • $atts (array): Array of the wp_mail() arguments.
    • to (string|string[]): Array or comma-separated list of email addresses to send the message.
    • subject (string): Email subject.
    • message (string): Message contents.
    • headers (string|string[]): Additional headers.
    • attachments (string|string[]): Paths to files to attach.

Examples

Prevent emails to a specific domain

add_filter( 'pre_wp_mail', 'prevent_emails_to_specific_domain', 10, 2 );
function prevent_emails_to_specific_domain( $return, $atts ) {
    $blocked_domain = '@example.com';

    if ( strpos( $atts['to'], $blocked_domain ) !== false ) {
        return false;
    }

    return $return;
}

This example prevents emails from being sent to email addresses with the domain “example.com”. If the recipient’s email address contains the blocked domain, the filter returns false and stops the email from being sent.

Add a custom header to all emails

add_filter( 'pre_wp_mail', 'add_custom_header_to_emails', 10, 2 );
function add_custom_header_to_emails( $return, $atts ) {
    $custom_header = 'X-Custom-Header: CustomHeaderValue';

    if ( is_array( $atts['headers'] ) ) {
        $atts['headers'][] = $custom_header;
    } else {
        $atts['headers'] .= "rn" . $custom_header;
    }

    return $return;
}

This example adds a custom header called “X-Custom-Header” with the value “CustomHeaderValue” to all outgoing emails.

Change the email subject for specific users

add_filter( 'pre_wp_mail', 'change_email_subject_for_specific_users', 10, 2 );
function change_email_subject_for_specific_users( $return, $atts ) {
    $special_user_email = '[email protected]';

    if ( $atts['to'] === $special_user_email ) {
        $atts['subject'] = 'Special Subject: ' . $atts['subject'];
    }

    return $return;
}

This example checks if the email is being sent to a specific user, and if so, changes the subject by adding “Special Subject: ” to the beginning of the original subject.

Log all outgoing emails

add_filter( 'pre_wp_mail', 'log_outgoing_emails', 10, 2 );
function log_outgoing_emails( $return, $atts ) {
    error_log( 'Email sent to: ' . $atts['to'] . ', Subject: ' . $atts['subject'] );

    return $return;
}

This example logs all outgoing emails, including their recipients and subjects, using the PHP error_log() function.

Send a copy of all emails to a specific address

add_filter( 'pre_wp_mail', 'send_copy_of_emails_to_specific_address', 10, 2 );
function send_copy_of_emails_to_specific_address( $return, $atts ) {
    $copy_email = '[email protected]';

    if ( is_array( $atts['to'] ) ) {
        $atts['to'][] = $copy_email;
    } else {
        $atts['to'] .= ',' . $copy_email;
    }

    return $return;
}

This example sends a copy of all outgoing emails to a specific email address, “[email protected]“, by adding the address to the “to” field.