Skip to content

Check SMTPUTF8 support before sending internationalized email - #55268

Merged
ahus1 merged 1 commit into
keycloak:mainfrom
ahus1:fix/55267-smtputf8-capability
Nov 17, 2026
Merged

ahus1 merged 1 commit into
keycloak:mainfrom
ahus1:fix/55267-smtputf8-capability

Conversation

@ahus1

@ahus1 ahus1 commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Closes #55267

The connected server's EHLO response is the reliable point to decide whether a message requiring SMTPUTF8 can 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, and git diff --check. The normal-send regression test independently covers non-ASCII sender, recipient, reply-to, and envelope sender addresses, asserting rejection before MAIL FROM.

AI agents assisted with the implementation, tests, and PR description. I reviewed the resulting code and test results.

@ahus1
ahus1 force-pushed the fix/55267-smtputf8-capability branch from 683dfcd to 565b284 Compare November 17, 2026 12:24
@ahus1 ahus1 changed the title Require SMTPUTF8 capability when Allow UTF-8 is enabled Check SMTPUTF8 support before sending internationalized email Nov 17, 2026
@ahus1
ahus1 requested a balanced review from Copilot November 17, 2026 12:26

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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
ahus1 force-pushed the fix/55267-smtputf8-capability branch from 565b284 to bf0e901 Compare November 17, 2026 12:36
@ahus1
ahus1 requested a balanced review from Copilot November 17, 2026 12:39

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block approval of the SMTPUTF8 capability-check changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@rmartinc rmartinc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ahus1! LGTM! I think that the test is much better now. Besides ascii emails are still sent like before.

@ahus1
ahus1 marked this pull request as ready for review November 17, 2026 17:37
@ahus1
ahus1 requested a review from a team as a code owner November 17, 2026 17:37
@ahus1
ahus1 merged commit eeceb5a into keycloak:main Nov 17, 2026
100 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Keycloak sends UTF-8 email when the SMTP server does not advertise SMTPUTF8

3 participants