Repository navigation
Check SMTPUTF8 support before sending internationalized email - #55268
Merged
Merged
Conversation
ahus1
force-pushed
the
fix/55267-smtputf8-capability
branch
from
November 17, 2026 12:24
683dfcd to
565b284
Compare
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The missing-capability tests bypass normal-send address checks, leaving rejection of each internationalized address field before MAIL FROM unverified when SMTPUTF8 is unavailable.
1 open issue
What changed in this PR
This PR addresses #55267 by checking SMTPUTF8 support before Keycloak sends internationalized email addresses, while preserving normal delivery for ASCII-only addresses.
Changes:
- Reject internationalized messages before the SMTP envelope when the server lacks SMTPUTF8; require the capability for connection tests whenever Allow UTF-8 is enabled.
- Add missing-capability regression tests and upgrade the shared GreenMail dependency.
- Document the behavior and configuration implications in the migration guide.
| File | Description |
|---|---|
tests/base/src/test/java/org/keycloak/tests/admin/SMTPConnectionTest.java |
Adds a local SMTP server and missing-capability test cases. |
test-framework/email-server/pom.xml |
Removes the local GreenMail version override. |
services/src/main/java/org/keycloak/email/freemarker/FreeMarkerEmailTemplateProvider.java |
Adds the connection-test hint to a copied configuration. |
services/src/main/java/org/keycloak/email/DefaultEmailSenderProvider.java |
Checks advertised SMTPUTF8 support before sending. |
server-spi-private/src/main/java/org/keycloak/email/EmailSenderProvider.java |
Defines the internal connection-test configuration hint. |
pom.xml |
Upgrades GreenMail to 2.1.15. |
docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc |
Explains SMTPUTF8 requirements for sends and connection tests. |
Review effort: Balanced
Closes keycloak#55267 Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com>
ahus1
force-pushed
the
fix/55267-smtputf8-capability
branch
from
November 17, 2026 12:36
565b284 to
bf0e901
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #55267
The connected server's
EHLOresponse is the reliable point to decide whether a message requiringSMTPUTF8can be sent. Angus Mail does not fail the send on its own when the capability is absent, so the sender checks it before issuing the SMTP envelope.The check for normal sends is limited to non-ASCII sender, recipient, reply-to, and envelope sender addresses. Subjects and display names are MIME-encoded, so their Unicode text alone does not require
SMTPUTF8. ASCII-only messages can continue through a server without the extension even when Allow UTF-8 is enabled.Test connection checks the capability whenever Allow UTF-8 is enabled, including for an ASCII-only test message, because that action should validate the configured mode. An internal hint is added to a copy of the test settings so the template provider keeps its existing send hook. The migration guide explains both cases and cites RFC 6531.
GreenMail was upgraded because the previous test version did not advertise
SMTPUTF8. A small local SMTP server covers the missing-capability cases without filtering GreenMail's response.Verified with
./mvnw -pl tests/base -am -Dtest=SMTPConnectionTest -Dsurefire.failIfNoSpecifiedTests=false test -q(15 tests passed),./mvnw -Pspotless spotless:check -pl services,server-spi-private,tests/base -q,./mvnw -Pspotless spotless:apply -q, andgit diff --check. The normal-send regression test independently covers non-ASCII sender, recipient, reply-to, and envelope sender addresses, asserting rejection beforeMAIL FROM.AI agents assisted with the implementation, tests, and PR description. I reviewed the resulting code and test results.