Keycloak Email: Configure SMTP for Notifications (2026)

Keycloak can send emails for a variety of events, but it won’t do so out of the box without a properly configured SMTP server.

Let’s see Keycloak send a password reset email.

First, you need a running Keycloak instance. For this example, we’ll assume it’s accessible at http://localhost:8080.

Navigate to your realm’s settings. In the left-hand menu, under "General," you’ll find "Email." Click on it.

Here’s where the magic happens. You’ll see a section for "SMTP Settings."

• SMTP Server: The hostname or IP address of your mail server. For testing, you can use a local SMTP server like MailHog or a service like smtp.mailtrap.io. Let’s use localhost for a local MailHog instance.
• SMTP Port: The port your SMTP server listens on. Typically 25 (unencrypted), 587 (STARTTLS), or 465 (SMTPS). MailHog defaults to 1025.
• Use Authentication: Toggle this if your SMTP server requires a username and password. For MailHog, this is usually false. For Mailtrap, it would be true.
• Username: If authentication is enabled, this is your SMTP username.
• Password: If authentication is enabled, this is your SMTP password.
• Enable TLS: Toggle this if your SMTP server uses TLS (STARTTLS or SMTPS). For MailHog, this is false. For most external providers, it’s true.
• From: The email address that will appear in the "From" field of the sent emails. This is often required by mail servers. Use something like noreply@example.com.
• From Display Name: An optional display name for the sender. Let’s leave this blank for now.
• Reply To: An optional email address for replies.
• Reply To Display Name: An optional display name for the reply-to address.

After filling in these details, click "Save."

Now, to test it, go to "Users" in your realm. Click "Create user." Fill in the required fields, including an email address for the user. Once created, select the user and click "Reset password."

If everything is configured correctly, Keycloak will send an email to the specified address. If you’re using MailHog, you’ll see the email appear in its web interface (usually http://localhost:8025).

The "From" address is crucial. Many SMTP servers will reject emails if this isn’t set or if it doesn’t match an authorized sender. The "From" address is not just for display; it’s part of the SMTP transaction.

Here’s the mental model: Keycloak acts as an email client. When an event triggers an email (like password reset, new user registration, etc.), Keycloak constructs the email content and then hands it off to the configured SMTP server for delivery. The SMTP server is responsible for the actual routing and sending of the email to the recipient’s mail server. Keycloak only initiates the connection and provides the message.

The most surprising thing about Keycloak’s email configuration is how often the "From" address causes issues, even when other settings seem correct. It’s not just a display field; it’s a critical part of the SMTP protocol and often needs to be a valid, authorized sender address on your SMTP server. Without it, many mail servers will silently drop the email or reject the connection.

If you’ve configured everything and still aren’t receiving emails, the next thing to check is the Keycloak server logs. They will often contain more detailed error messages from the underlying JavaMail API that Keycloak uses.