Repository navigation
Can't send e-mails to international e-mail addresses: bad UTF-8 syntax #41023
Description
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 syntaxappears 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.
Activity
rmartinc commentedon Jul 16, 2025
My feeling here is that we need to add the property
mail.mime.allowutf8totrueto the configuration to allow this. Can you please test adding something like this to DefaultEmailSenderProvider?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!
11 remaining items
Allow and control sending UTF-8 emails in the default email sender impl
Allow and control sending UTF-8 emails in the default email sender impl
Allow and control sending UTF-8 emails in the default email sender impl
Allow and control sending UTF-8 emails in the default email sender impl
Allow and control sending UTF-8 emails in the default email sender impl
Allow and control sending UTF-8 emails in the default email sender impl
Allow and control sending UTF-8 emails in the default email sender impl