Can't send e-mails to international e-mail addresses: bad UTF-8 syntax

Before reporting an issue

I have read and understood the above terms for submitting issues, and I understand that my issue may be closed without action if I do not follow them.

Area

login/ui

Describe the bug

When attempting to send an e-mail to an international e-mail address from Keycloak, the following error appears in the log:

Jul 09 10:26:42 login docker[1200]: jakarta.mail.SendFailedException: Invalid Addresses;
Jul 09 10:26:42 login docker[1200]:   nested exception is:
Jul 09 10:26:42 login docker[1200]:         org.eclipse.angus.mail.smtp.SMTPAddressFailedException: 500 5.5.2 Error: bad UTF-8 syntax
Jul 09 10:26:42 login docker[1200]:         at org.eclipse.angus.mail.smtp.SMTPTransport.rcptTo(SMTPTransport.java:2097)
Jul 09 10:26:42 login docker[1200]:         at org.eclipse.angus.mail.smtp.SMTPTransport.sendMessage(SMTPTransport.java:1291)
Jul 09 10:26:42 login docker[1200]:         at org.keycloak.email.DefaultEmailSenderProvider.send(DefaultEmailSenderProvider.java:86)
Jul 09 10:26:42 login docker[1200]:         at org.keycloak.email.DefaultEmailSenderProvider.send(DefaultEmailSenderProvider.java:72)
Jul 09 10:26:42 login docker[1200]:         at org.keycloak.email.freemarker.FreeMarkerEmailTemplateProvider.send(FreeMarkerEmailTemplateProvider.java:289)
Jul 09 10:26:42 login docker[1200]:         at org.keycloak.email.freemarker.FreeMarkerEmailTemplateProvider.send(FreeMarkerEmailTemplateProvider.java:283)
Jul 09 10:26:42 login docker[1200]:         at org.keycloak.email.freemarker.FreeMarkerEmailTemplateProvider.sendSmtpTestEmail(FreeMarkerEmailTemplateProvider.java:128)
Jul 09 10:26:42 login docker[1200]:         at org.keycloak.services.resources.admin.RealmAdminResource.testSMTPConnection(RealmAdminResource.java:1148)
Jul 09 10:26:42 login docker[1200]:         at org.keycloak.services.resources.admin.RealmAdminResource$quarkusrestinvoker$testSMTPConnection_0bc3cac9c894e7b29eb4c1f2d80a099cba7bdf38.invoke(Unknown Source)
Jul 09 10:26:42 login docker[1200]:         at org.jboss.resteasy.reactive.server.handlers.InvocationHandler.handle(InvocationHandler.java:29)
Jul 09 10:26:42 login docker[1200]:         at io.quarkus.resteasy.reactive.server.runtime.QuarkusResteasyReactiveRequestContext.invokeHandler(QuarkusResteasyReactiveRequestContext.java:141)
Jul 09 10:26:42 login docker[1200]:         at org.jboss.resteasy.reactive.common.core.AbstractResteasyReactiveContext.run(AbstractResteasyReactiveContext.java:147)
Jul 09 10:26:42 login docker[1200]:         at io.quarkus.vertx.core.runtime.VertxCoreRecorder$15.runWith(VertxCoreRecorder.java:638)
Jul 09 10:26:42 login docker[1200]:         at org.jboss.threads.EnhancedQueueExecutor$Task.doRunWith(EnhancedQueueExecutor.java:2675)
Jul 09 10:26:42 login docker[1200]:         at org.jboss.threads.EnhancedQueueExecutor$Task.run(EnhancedQueueExecutor.java:2654)
Jul 09 10:26:42 login docker[1200]:         at org.jboss.threads.EnhancedQueueExecutor.runThreadBody(EnhancedQueueExecutor.java:1627)
Jul 09 10:26:42 login docker[1200]:         at org.jboss.threads.EnhancedQueueExecutor$ThreadBody.run(EnhancedQueueExecutor.java:1594)
Jul 09 10:26:42 login docker[1200]:         at org.jboss.threads.DelegatingRunnable.run(DelegatingRunnable.java:11)
Jul 09 10:26:42 login docker[1200]:         at org.jboss.threads.ThreadLocalResettingRunnable.run(ThreadLocalResettingRunnable.java:11)
Jul 09 10:26:42 login docker[1200]:         at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
Jul 09 10:26:42 login docker[1200]:         at java.base/java.lang.Thread.run(Thread.java:1583)
Jul 09 10:26:42 login docker[1200]: Caused by: org.eclipse.angus.mail.smtp.SMTPAddressFailedException: 500 5.5.2 Error: bad UTF-8 syntax
Jul 09 10:26:42 login docker[1200]:         at org.eclipse.angus.mail.smtp.SMTPTransport.rcptTo(SMTPTransport.java:1997)
Jul 09 10:26:42 login docker[1200]:         ... 20 more

Using the "Enable Debug SMTP" option in Realm Settings > Email > Connection & Authentication, we can see that Keycloak does not encode the address properly when communicating with the SMTP server, replacing "öüä" with "��"

Jul 09 10:26:42 login docker[1200]: DEBUG SMTP: AUTH LOGIN succeeded
Jul 09 10:26:42 login docker[1200]: DEBUG SMTP: use8bit false
Jul 09 10:26:42 login docker[1200]: MAIL FROM:<keycloak@test.com>
Jul 09 10:26:42 login docker[1200]: 250 2.1.0 Ok
Jul 09 10:26:42 login docker[1200]: RCPT TO:<test+���@test.com>
Jul 09 10:26:42 login docker[1200]: 500 5.5.2 Error: bad UTF-8 syntax
Jul 09 10:26:42 login docker[1200]: DEBUG SMTP: Invalid Addresses
Jul 09 10:26:42 login docker[1200]: DEBUG SMTP:   test+öüä@test.com
Jul 09 10:26:42 login docker[1200]: DEBUG SMTP: Sending failed because of invalid destination addresses
Jul 09 10:26:42 login docker[1200]: RSET
Jul 09 10:26:42 login docker[1200]: 250 2.0.0 Ok
Jul 09 10:26:42 login docker[1200]: DEBUG SMTP: MessagingException while sending, THROW:
Jul 09 10:26:42 login docker[1200]: jakarta.mail.SendFailedException: Invalid Addresses;

Version

26.2.4 (can be reproduced in 26.3.0 as well)

Regression

The issue is a regression

Expected behavior

E-mails can be sent to international e-mail addresses containing UTF-8 characters

Actual behavior

When trying to send an e-mail from Keycloak to an international e-mail address, e.g. password reset/verify email actions or by using the "Test connection" button in Realm Settings > Email > Connection & Authentication, "Error! Failed to send email" is shown in the UI, and org.eclipse.angus.mail.smtp.SMTPAddressFailedException: 500 5.5.2 Error: bad UTF-8 syntax appears in the Keycloak logs on the server` is shown in the Keycloak log on the server.

How to Reproduce?

Create a user with an international e-mail address, assign the "Verify e-mail" required action and set a password
Attempt to log in with the user
A "Failed to send email" error appears
org.eclipse.angus.mail.smtp.SMTPAddressFailedException: 500 5.5.2 Error: bad UTF-8 syntax appears in the Keycloak logs on the server

Anything else?

The behavior can be reproduced with a 'real' SMTP server/relay like Postfix, as well as a 'mock' e-mail server like Maildev. In case of Maildev however, Keycloak is able to send e-mails to Maildev, but the address isn't displayed correctly in the Maildev UI

My theory is that since Maildev is a 'mock' mail server, it doesn't verify e-mail addresses to the same extent as e.g. Postfix.

My feeling here is that we need to add the property mail.mime.allowutf8 to true to the configuration to allow this. Can you please test adding something like this to DefaultEmailSenderProvider?

diff --git a/services/src/main/java/org/keycloak/email/DefaultEmailSenderProvider.java b/services/src/main/java/org/keycloak/email/DefaultEmailSenderProvider.java
index eea69eb905..4534518841 100644
--- a/services/src/main/java/org/keycloak/email/DefaultEmailSenderProvider.java
+++ b/services/src/main/java/org/keycloak/email/DefaultEmailSenderProvider.java
@@ -147,6 +147,8 @@ public class DefaultEmailSenderProvider implements EmailSenderProvider {
         // https://jakarta.ee/specifications/mail/2.0/jakarta-mail-spec-2.0#a823
         props.setProperty("mail.from", from);
 
+        props.setProperty("mail.mime.allowutf8", "true");
+
         return props;
     }

I don't think it would be easy for us to test this. If it works for you we need to add a new property to the email configuration (also in the admin console).

Moving this to enhancement.

Thanks!

Allow and control sending UTF-8 emails in the default email sender impl

Navigation Menu

Repository navigation

Can't send e-mails to international e-mail addresses: bad UTF-8 syntax #41023

Before reporting an issue

Area

Describe the bug

Version

Regression

Expected behavior

Actual behavior

How to Reproduce?

Anything else?

11 remaining items

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Can't send e-mails to international e-mail addresses: bad UTF-8 syntax #41023

Description

Before reporting an issue

Area

Describe the bug

Version

Regression

Expected behavior

Actual behavior

How to Reproduce?

Anything else?

Activity

rmartinc commented on Jul 16, 2025

11 remaining items

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions