Add jetpack_account_protection_send_auth_email filter for custom verification email handling #47999

[yaswanthkumar1995]

Fixes #47999

Summary

Adds a jetpack_account_protection_send_auth_email filter in Email_Service::api_send_auth_email() that allows sites to handle the Account Protection verification email locally instead of via the WPCOM API.

Problem

The password-detection verification email is sent entirely through the WPCOM API, bypassing wp_mail(). Sites using custom email branding (e.g. wrapping all outgoing emails in branded HTML templates) cannot intercept or customize this email, creating brand inconsistency.

Solution

A new jetpack_account_protection_send_auth_email filter fires before the WPCOM API call:

$handled = apply_filters(
    'jetpack_account_protection_send_auth_email',
    false,
    $user_id,
    $auth_code,
    $blog_id
);

Parameter	Type	Description
$handled	bool	Whether the email has been handled. Default false.
$user_id	int	The user ID.
$auth_code	string	The 6-digit verification code.
$blog_id	int|false	The blog ID.

When the filter returns truthy, the WPCOM API call is skipped — the site is responsible for delivering the email. When no filter is attached, behavior is unchanged.

Changelog

• jetpack-account-protection: Minor — Added jetpack_account_protection_send_auth_email filter

Testing instructions:

1. Verify default behavior is unchanged (no filter attached):

   • Enable Account Protection on a Jetpack-connected site
   • Log in with a correct password to trigger the verification email flow
   • Confirm the verification email is still sent via the WPCOM API as before

2. Verify the filter short-circuits the API call:

   • Add the following to a plugin or theme's functions.php:

     add_filter( 'jetpack_account_protection_send_auth_email', function( $handled, $user_id, $auth_code, $blog_id ) {
         // Send via wp_mail() instead
         $user = get_userdata( $user_id );
         wp_mail(
             $user->user_email,
             'Your verification code',
             sprintf( 'Your code is: %s', $auth_code )
         );
         return true;
     }, 10, 4 );

   • Log in with a correct password to trigger the verification flow
   • Confirm the email arrives via wp_mail() (with any site branding applied) instead of the Jetpack-branded WPCOM email
   • Confirm the verification code in the email works correctly on the verification screen

3. Verify filter returning false continues normal flow:

   • Change the filter callback to return false;
   • Trigger the verification flow again
   • Confirm the email is sent via the WPCOM API as usual

4. Run unit tests:

   cd projects/packages/account-protection
   composer phpunit

   • All 89 tests should pass

Does this pull request change what data or activity we track or use?

No. This PR does not change any data tracking or collection. It only adds a filter hook that allows sites to optionally handle the verification email delivery locally. When no filter is attached, the existing WPCOM API behavior is completely unchanged. No new data is sent, stored, or exposed.

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

[yaswanthkumar1995]

Hi @nandotess — I've implemented the proposed solution and opened a PR:

What's included

• A jetpack_account_protection_send_auth_email filter in Email_Service::api_send_auth_email() that fires before the WPCOM API call, passing $handled, $user_id, $auth_code, and $blog_id
• When the filter returns truthy, the API call is skipped — the site handles delivery (e.g. via wp_mail())
• Default behavior is completely unchanged when no filter is attached
• Two new PHPUnit tests covering both the short-circuit and pass-through paths
• Changelog entry (minor/added)

Could someone from the team assign this and review when you get a chance? Thanks!

[ArSn]

Thank you for this, it looks good and I have also tested it to verify we still receive the auth code via our servers by default.

The failing tests seem unrelated to these changes, I am working on figuring that out, and will merge this once I do.

[yaswanthkumar1995]

@ArSn also kindly assign this to me.