wp_mail_succeeded action in wp_mail()

[birgire]

To complement the wp_mail_failed action in wp_mail() we could add the wp_mail_succeeded action.

Here's a suggestion to use e.g.:

$status = $phpmailer->send();

if ( $status ) {

	$mail_data = compact( 'to', 'subject', 'message', 'headers', 'attachments' );

	/**
	 * Fires after PHPMailer has successfully sent a mail.
	 *
	 * @since x.y.z
	 *
	 * @param array $mail_data An array containing the mail recipient, subject, message, headers, and attachments.
	 */
	do_action( 'wp_mail_succeeded', $mail_data );		
}

in wp_mail() instead of:

return $phpmailer->send();

ps: In BuddyPress we have e.g. both bp_send_email_failure and bp_send_email_success actions.

This PR adds wp_mail_succeeded action.

Trac ticket: https://core.trac.wordpress.org/ticket/53826

[birgire]

@donmhico Thanks for the patch, it looks good.

[hellofromTonya]

Looking at the new action, 'wp_mail_succeeded', why is it in the catch and not the try? If it succeeds, it would not go into the catch.

Today is 5.9 feature freeze. With questions pending, punting this one to 6.0. As that milestone isn't available yet, setting it to Future Release. Once available, please feel free to move it into the milestone.

[davidbaumwald]

@hellofromTonya From what I can tell, the patch is good. The wp_mail_succeeded action is in the try section, and the wp_mail_failed action is in the catch.

Whether or not this can be pulled back in for 5.9 is another question, but did want to clear up the the current PR looks OK.

[hellofromTonya]

@davidbaumwald you're right. Picture me doing a facepalm (doh). Pulling it back in and marking for commit.

[davidbaumwald]

@hellofromTonya Thanks! I'll pick this one up for review and commit.

[davidbaumwald]

Added disclaimer, minor spelling corrections

[davidbaumwald]

In 52083:

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.

Committed to core via changeset: https://core.trac.wordpress.org/changeset/52083

[davidbaumwald]

Marking this with needs-dev-note for a small call-out on the Misc Dev note for the new filter.

[audrasjb]

Dev note published: ​https://make.wordpress.org/core/2022/01/04/miscellaneous-core-changes-in-wordpress-5-9/