From d6de0e449829ac98a5644bddd67b12ddc06f5cad Mon Sep 17 00:00:00 2001
From: davidbaumwald <davidbaumwald@git.wordpress.org>
Date: Tue, 9 Nov 2021 22:27:59 +0000
Subject: [PATCH] Mail: Add `wp_mail_succeeded` hook to `wp_mail`.

Adds a new `wp_mail_succeeded` action in `wp_mail` after the mail is sent.  Also, adds a disclaimer to the hook's docblock, clarifying that the hook's firing doesn't necessarily mean the recipient received the mail, only that the mail was processed without any errors.

Props birgire, donmhico, johnbillion.
Fixes #53826.
Built from https://develop.svn.wordpress.org/trunk@52083


git-svn-id: http://core.svn.wordpress.org/trunk@51675 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/pluggable.php | 25 ++++++++++++++++++++-----
 wp-includes/version.php   |  2 +-
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php
index e30fad1808..17a23e3cd8 100644
--- a/wp-includes/pluggable.php
+++ b/wp-includes/pluggable.php
@@ -537,13 +537,28 @@ if ( ! function_exists( 'wp_mail' ) ) :
 		 */
 		do_action_ref_array( 'phpmailer_init', array( &$phpmailer ) );
 
+		$mail_data = compact( 'to', 'subject', 'message', 'headers', 'attachments' );
+
 		// Send!
 		try {
-			return $phpmailer->send();
-		} catch ( PHPMailer\PHPMailer\Exception $e ) {
+			$send = $phpmailer->send();
 
-			$mail_error_data                             = compact( 'to', 'subject', 'message', 'headers', 'attachments' );
-			$mail_error_data['phpmailer_exception_code'] = $e->getCode();
+			/**
+			 * Fires after PHPMailer has successfully sent a mail.
+			 *
+			 * The firing of this action does not necessarily mean that the recipient received the
+			 * email successfully. It only means that the `send` method above was able to
+			 * process the request without any errors.
+			 *
+			 * @since 5.9.0
+			 *
+			 * @param array $mail_data An array containing the mail recipient, subject, message, headers, and attachments.
+			 */
+			do_action( 'wp_mail_succeeded', $mail_data );
+
+			return $send;
+		} catch ( PHPMailer\PHPMailer\Exception $e ) {
+			$mail_data['phpmailer_exception_code'] = $e->getCode();
 
 			/**
 			 * Fires after a PHPMailer\PHPMailer\Exception is caught.
@@ -553,7 +568,7 @@ if ( ! function_exists( 'wp_mail' ) ) :
 			 * @param WP_Error $error A WP_Error object with the PHPMailer\PHPMailer\Exception message, and an array
 			 *                        containing the mail recipient, subject, message, headers, and attachments.
 			 */
-			do_action( 'wp_mail_failed', new WP_Error( 'wp_mail_failed', $e->getMessage(), $mail_error_data ) );
+			do_action( 'wp_mail_failed', new WP_Error( 'wp_mail_failed', $e->getMessage(), $mail_data ) );
 
 			return false;
 		}
diff --git a/wp-includes/version.php b/wp-includes/version.php
index d4961e30f9..9ec5252732 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.9-alpha-52082';
+$wp_version = '5.9-alpha-52083';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.