Keycloak sends email for address verification, password recovery and required actions an admin triggers for a user. None of it can be delivered until the realm has an SMTP server. There is no extension to install: every realm has its own Email tab in the admin console.
| Setting | Value |
|---|---|
| SMTP host | smtp.postwing.app |
| Port | 587 |
| Encryption | STARTTLS (the connection is upgraded to TLS before login) |
| Username | The login of an SMTP token for your domain |
| Password | The password of that token — shown once, when the token is created |
Select the realm your users log in to, then open Realm settings → Email:
| Field | Value |
|---|---|
| From | noreply@your-domain.com — on your verified domain |
| From display name | Your product name |
| Reply to | Optional, e.g. support@your-domain.com |
| Host | smtp.postwing.app |
| Port | 587 |
| Encryption | Enable StartTLS on, Enable SSL off |
| Authentication | On |
| Username | The login of an SMTP token for your domain |
| Authentication Type | password (shown in recent versions) |
| Password | That token's password |
587; Enable SSL goes with port 465. Turning both on, or SSL on 587, fails the TLS handshake. SMTP alone sends nothing. Open Realm settings → Login and enable the flows that use it:
The same settings live in the realm's smtpServer map, so kcadm.sh can set them — handy for scripted or repeated environments:
# Log in to the admin CLI once
kcadm.sh config credentials --server https://sso.your-domain.com \
--realm master --user admin
# Set the realm's SMTP server — every value is a string
kcadm.sh update realms/myrealm \
-s 'smtpServer.host="smtp.postwing.app"' \
-s 'smtpServer.port="587"' \
-s 'smtpServer.starttls="true"' \
-s 'smtpServer.ssl="false"' \
-s 'smtpServer.auth="true"' \
-s 'smtpServer.user="token-login@your-domain.com"' \
-s 'smtpServer.password="your-token-password"' \
-s 'smtpServer.from="noreply@your-domain.com"' \
-s 'smtpServer.fromDisplayName="Acme"'Press Test connection at the bottom of the Email tab. Keycloak sends a message to the email address of the admin you are logged in as, so give that account an address first. On failure it shows the server's error in a banner.
| Error | Cause and fix |
|---|---|
| Test connection is disabled | Your admin user has no email address. |
Couldn't connect to host / timeout | Outbound port blocked — use 8587 with StartTLS or 8465 with SSL. |
| SSL handshake error | Enable SSL switched on for port 587. Use StartTLS instead. |
535 Authentication failed | Wrong token login or password, or Authentication left off. |
| Test works, users get no reset email | Forgot password is off on the Login tab, or you configured a different realm. |
| Mail goes to spam | From is not on your verified domain. |
In the admin console, pick the realm, then Realm settings → Email tab. Email is configured per realm: the master realm's settings do not apply to the realm your users log in to, so set up each realm that sends mail.
For port 587 turn on Enable StartTLS and leave Enable SSL off. For port 465 do the opposite: Enable SSL on, StartTLS off. Enabling SSL on port 587 is the most common reason the connection test fails with a handshake error.
The test email goes to the admin user you are logged in as, so that user needs an email address. Keycloak says so above the button; add an address to your admin account in the master realm and try again.
Configuring SMTP does not switch those flows on. Go to Realm settings → Login tab and enable Verify email and Forgot password. Without them Keycloak never generates those messages, however the Email tab is set up.
Yes. The Password field accepts a vault reference such as ${vault.smtp_password} when a vault provider is configured, and Keycloak reads the secret from the vault at send time instead of storing it in the realm.
Check the From field on the Email tab. It must be an address on the domain you verified, or DKIM and SPF do not align with it. Put a support address in Reply to if users should be able to answer.