Mail: New Version for Multipart solution #9500

SirLouen · 2025-08-17T13:56:43Z

This is the new version that solves all the problems without having to do any upgrade + not having to modify anything in the PHPMailer part. More info and testing info below.

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

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2025-08-17T13:56:53Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props sirlouen, westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2025-08-17T14:26:21Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

src/wp-includes/pluggable.php

westonruter · 2025-11-10T21:14:55Z

src/wp-includes/pluggable.php

-			if ( false !== stripos( $content_type, 'multipart' ) && ! empty( $boundary ) ) {
-				$phpmailer->addCustomHeader( sprintf( 'Content-Type: %s; boundary="%s"', $content_type, $boundary ) );
-			}


I tried restoring this block of code and the tests still pass. Is that expected?

In other words, should there be a test that checks for only one Content-Type header being present?

This was the original issue. I'm not sure if this ever worked, but for long time, everyone thought this was doing something. I've been playing a lot with the headers both in other tickets and PHPMailer, and then I got back to this ticket and I noted that this was not been triggered at all on multipart, because if you check the logic above, the default condition of the switch case, is never reached (because the Content-Type is already set in the corresponding case).

If anything happens to drops into the default it is not going to be a Content-Type and for this reason, this is never going to be triggered.

So it can be safely removed, it's useless.

I added 2111d68 to ensure there is only one header sent. Without this removed, the assertion now fails with:

1) Tests_Pluggable_wpMail::test_wp_mail_custom_boundaries Expected only one Content-Type header to be sent. Saw: multipart/mixed; boundary="----=_Part_4892_25692638.1192452070893"; boundary="----=_Part_4892_25692638.1192452070893" multipart/mixed; boundary="----=_Part_4892_25692638.1192452070893"; charset= Failed asserting that actual size 2 matches expected size 1.

…into patch/15448v2

westonruter · 2025-11-11T01:51:36Z

tests/phpunit/tests/pluggable/wpMail.php

+		$this->assertArrayHasKey( 'Content-Type', $headers, 'Expected Content-Type header to be sent.' );
+		$content_type_headers = (array) $headers['Content-Type'];
+		$this->assertCount( 1, $content_type_headers, "Expected only one Content-Type header to be sent. Saw:\n" . implode( "\n", $content_type_headers ) );
+		$this->assertSame( 'multipart/mixed; boundary="----=_Part_4892_25692638.1192452070893"; charset=', $content_type_headers[0], 'Expected Content-Type to match.' );


What I don't get is why the Content-Type header ends in charset=. I guess PHPMailer adds this?

Gemini seems to have explained it well:

I've finished reviewing PHPMailer.php. The Content-Type header is constructed in the getMailMIME() method, which is called by createHeader().

In the test, wp_mail passes a raw MIME message to PHPMailer's $body. PHPMailer's setMessageType() method then determines the message_type as 'plain' because it sees a single body, not a parsed multipart structure.

For a 'plain' message, getMailMIME() constructs the Content-Type header as: 'Content-Type: ' . $this->ContentType . '; charset=' . $this->CharSet.

In wp_mail, the provided Content-Type header (multipart/mixed; boundary="...") is parsed. Since there's no charset, wp_mail sets $phpmailer->CharSet to ''.

Therefore, the final header becomes: Content-Type: multipart/mixed; boundary="..."; charset=, which is what the test asserts. This is an intentional behavior in PHPMailer for pre-formatted MIME messages, and the test correctly verifies it.

And the charset is not really relevant in the top-level header for the multipart/mixed content type, since the boundary is all that matters. The actual charset is set on one of the parts.

westonruter

I'm not an expert on mail headers, but from all I can tell this is right.

Gemini also likes it:

Here is my revised review of the changes:

This is an excellent set of changes that improves the handling of multipart Content-Type headers in wp_mail() and adds robust, valuable test coverage.

src/wp-includes/pluggable.php

Good Refactor: The logic for handling multipart Content-Type headers has been simplified and made more robust. Moving away from addCustomHeader to directly setting the $content_type variable which is then passed to PHPMailer is a cleaner implementation.

Improved Consistency: The new logic to normalize the multipart/ subtype to lowercase and correctly quote the boundary enhances consistency and reduces the chance of malformed headers.

tests/phpunit/tests/pluggable/wpMail.php

Precise Assertions: The updated assertions in test_wp_mail_custom_boundaries() are a significant improvement. Using assertSame() provides a much stricter and more reliable test than the previous assertStringContainsString().

Excellent Test Coverage: The two new tests, test_wp_mail_plain_and_html() and test_wp_mail_plain_and_html_workaround(), are great additions. They cover common, real-world scenarios for sending multipart emails.

Modern PHP: The use of a static function (a static closure) in test_wp_mail_plain_and_html_workaround() is a nice touch. It's a modern, clean way to handle the action callback, keeping the logic scoped to the test itself. The WP_PHPMailer type hint is also good practice.

This is a high-quality contribution. The refactoring is sound, and the tests are well-written and thorough. This looks good to go.

This improves how `wp_mail()` handles `Content-Type` headers for multipart messages, preventing cases where the header could be duplicated. Developed in #9500 Props SirLouen, gitlost, rmccue, westi, MattyRob, bgermann, nacin, SergeyBiryukov, dd32, MikeHansenMe, Kleor, kitchin, JeffMatson, abcd95, westonruter, christinecooper, JohnVieth, dawidadach, imokweb, ayeshrajans, lakshyajeet, tusharbharti, sajjad67. Fixes #15448. git-svn-id: https://develop.svn.wordpress.org/trunk@61201 602fd350-edb4-49c9-b593-d223f7449a82

github-actions · 2025-11-11T02:35:14Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 61201
GitHub commit: 024bbfc

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

This improves how `wp_mail()` handles `Content-Type` headers for multipart messages, preventing cases where the header could be duplicated. Developed in WordPress/wordpress-develop#9500 Props SirLouen, gitlost, rmccue, westi, MattyRob, bgermann, nacin, SergeyBiryukov, dd32, MikeHansenMe, Kleor, kitchin, JeffMatson, abcd95, westonruter, christinecooper, JohnVieth, dawidadach, imokweb, ayeshrajans, lakshyajeet, tusharbharti, sajjad67. Fixes #15448. Built from https://develop.svn.wordpress.org/trunk@61201 git-svn-id: http://core.svn.wordpress.org/trunk@60537 1a063a9b-81f0-0310-95a4-ce76da25c4cd

This improves how `wp_mail()` handles `Content-Type` headers for multipart messages, preventing cases where the header could be duplicated. Developed in WordPress/wordpress-develop#9500 Props SirLouen, gitlost, rmccue, westi, MattyRob, bgermann, nacin, SergeyBiryukov, dd32, MikeHansenMe, Kleor, kitchin, JeffMatson, abcd95, westonruter, christinecooper, JohnVieth, dawidadach, imokweb, ayeshrajans, lakshyajeet, tusharbharti, sajjad67. Fixes #15448. Built from https://develop.svn.wordpress.org/trunk@61201 git-svn-id: https://core.svn.wordpress.org/trunk@60537 1a063a9b-81f0-0310-95a4-ce76da25c4cd

@SirLouen

This improves how `wp_mail()` handles `Content-Type` headers for multipart messages, preventing cases where the header could be duplicated. Developed in WordPress/wordpress-develop#9500 WP:Props SirLouen, gitlost, rmccue, westi, MattyRob, bgermann, nacin, SergeyBiryukov, dd32, MikeHansenMe, Kleor, kitchin, JeffMatson, abcd95, westonruter, christinecooper, JohnVieth, dawidadach, imokweb, ayeshrajans, lakshyajeet, tusharbharti, sajjad67. Fixes https://core.trac.wordpress.org/ticket/15448. --- Merges https://core.trac.wordpress.org/changeset/61201 / WordPress/wordpress-develop@024bbfcc4c to ClassicPress.

* WP-r61201: Mail: Improve multipart message handling in `wp_mail()`. This improves how `wp_mail()` handles `Content-Type` headers for multipart messages, preventing cases where the header could be duplicated. Developed in WordPress/wordpress-develop#9500 WP:Props SirLouen, gitlost, rmccue, westi, MattyRob, bgermann, nacin, SergeyBiryukov, dd32, MikeHansenMe, Kleor, kitchin, JeffMatson, abcd95, westonruter, christinecooper, JohnVieth, dawidadach, imokweb, ayeshrajans, lakshyajeet, tusharbharti, sajjad67. Fixes https://core.trac.wordpress.org/ticket/15448. --- Merges https://core.trac.wordpress.org/changeset/61201 / WordPress/wordpress-develop@024bbfcc4c to ClassicPress. * Update callback type hint to MockPHPMailer in test Changed the type hint from WP_PHPMailer to MockPHPMailer in the $set_alt_body callback within the wpMail test. This ensures the callback matches the actual mock object used in the test environment. --------- Co-authored-by: Weston Ruter <[email protected]> CP:Props mattyrob, xxsimoxx

westonruter reviewed Nov 3, 2025

View reviewed changes

src/wp-includes/pluggable.php Outdated Show resolved Hide resolved

SirLouen added 4 commits November 5, 2025 14:44

Mail: New Version for Multipart solution

fbe204e

Much simpler regex

22d6686

Fixing Little Typo

9787007

Fixing this test, why using iconv_mime_decode_headers?

883983c

SirLouen force-pushed the patch/15448v2 branch from ce1c83f to 883983c Compare November 5, 2025 13:44

The Weston's Regex

1fd5ac9

adamziel mentioned this pull request Nov 5, 2025

[Website] Support previewing WordPress and Gutenberg branches, not just PRs WordPress/wordpress-playground#2868

Merged

Merge branch 'trunk' into patch/15448v2

e5f5b07

westonruter reviewed Nov 10, 2025

View reviewed changes

westonruter and others added 3 commits November 10, 2025 13:16

Add assertion to ensure boundary directive is matched in header

8c5ea89

Add since tag for improved multipart message handling

8acd7e4

Fix assert

ee57f4f

SirLouen requested a review from westonruter November 10, 2025 23:37

westonruter added 2 commits November 10, 2025 17:48

Update assertions to account for deleted addCustomHeader code

3b9179e

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

2111d68

…into patch/15448v2

westonruter reviewed Nov 11, 2025

View reviewed changes

Eliminate method in favor of closure

1c55eae

westonruter approved these changes Nov 11, 2025

View reviewed changes

github-actions bot closed this Nov 11, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Mail: New Version for Multipart solution #9500

Mail: New Version for Multipart solution #9500

Uh oh!

SirLouen commented Aug 17, 2025

Uh oh!

github-actions bot commented Aug 17, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Aug 17, 2025

Uh oh!

Uh oh!

westonruter Nov 10, 2025

Uh oh!

westonruter Nov 10, 2025

Uh oh!

SirLouen Nov 10, 2025

Uh oh!

westonruter Nov 11, 2025

Uh oh!

westonruter Nov 11, 2025

Uh oh!

westonruter Nov 11, 2025

Uh oh!

westonruter left a comment

Uh oh!

github-actions bot commented Nov 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Mail: New Version for Multipart solution #9500

Mail: New Version for Multipart solution #9500

Uh oh!

Conversation

SirLouen commented Aug 17, 2025

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

Uh oh!

github-actions bot commented Aug 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Aug 17, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

Uh oh!

westonruter Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

westonruter Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

SirLouen Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

westonruter Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

westonruter Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

westonruter Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

src/wp-includes/pluggable.php

tests/phpunit/tests/pluggable/wpMail.php

Uh oh!

github-actions bot commented Nov 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Aug 17, 2025 •

edited

Loading

`src/wp-includes/pluggable.php`

`tests/phpunit/tests/pluggable/wpMail.php`