Keycloak SMTP Configuration: Configure and Test Email

Keycloak uses email for verify-email links, password-reset messages, execute-actions email, and admin test mail. All of those features depend on the realm SMTP configuration under Realm settings → Email.

This guide shows how to configure SMTP in Keycloak, test that delivery works, and fix common connection, TLS, and authentication errors on Keycloak 26.7.3. The lab uses a plain catcher on 127.0.0.1:1025 with host-network Podman so 127.0.0.1 inside the container matches the listener on the host.

What is Keycloak SMTP configuration?

Keycloak does not deliver email directly to Gmail, Outlook, or another user's mailbox. Instead, Keycloak connects to an SMTP server (mail relay). The relay accepts the message from Keycloak and delivers it to the recipient's mail system.

Keycloak
   |
   | SMTP connection
   | host + port + TLS + authentication
   v
+-------------+
| SMTP relay  |
+-------------+
   |
   | delivers email
   v
Recipient mailbox

The settings under Realm settings → Email tell Keycloak how to connect to that SMTP relay.

Keycloak uses the realm SMTP configuration for test messages, verification emails, and password-reset emails:

Features such as email verification and password reset depend on the realm's SMTP configuration. Some user-facing flows intentionally show a generic confirmation message for security reasons, while SMTP test or Admin API calls can return an error when Keycloak cannot send the message.

Configure SMTP in Keycloak

Open Realm settings → Email in the Admin Console. Fill the sender fields first, then the connection and authentication settings for your SMTP relay.

Sender fields

Host, port and authentication

Set Host, Port, SSL, StartTLS, and Authentication to match your provider documentation, then click Save.

For the local lab, set Port to 1025 and leave Enable SSL, Enable StartTLS, and Authentication disabled unless your relay requires them.

The lab profile below was tested on Keycloak 26.7.3 against a local catcher. Provider rows in later sections follow vendor documentation and were not exercised in this lab:

Lab profile for a local catcher (no encryption, no authentication):

host=127.0.0.1  port=1025  ssl=false  starttls=false  auth=false

Configure SMTP with the Admin REST API

The realm representation exposes SMTP settings as an smtpServer map. The same values you enter in the Admin Console can be sent through the Admin REST API:

"smtpServer": {
  "host": "smtp.example.com",
  "port": "587",
  "from": "keycloak@example.com",
  "starttls": "true",
  "ssl": "false",
  "auth": "true"
}

Use the Admin Console for first-time setup. The REST API is useful for automation once the values are known.

SSL vs STARTTLS

STARTTLS starts as a normal SMTP connection and then upgrades that connection to TLS. Implicit TLS/SSL starts the connection encrypted from the first byte.

These are common SMTP conventions, but the provider's documentation is authoritative:

  STARTTLS (port 587)                 Implicit TLS (port 465)
  ┌────────┐  EHLO   ┌────────┐      ┌────────┐  TLS first  ┌────────┐
  │Keycloak│ ──────► │  SMTP  │      │Keycloak│ ──────────► │  SMTP  │
  │        │ ◄────── │ relay  │      │        │  encrypted  │ relay  │
  │        │ STARTTLS│        │      │        │  session    │        │
  │        │ ──────► │        │      └────────┘             └────────┘
  └────────┘  MAIL   └────────┘

Provider examples:

Note: the Gmail rows above describe SMTP transport only. Keycloak's built-in XOAUTH2 SMTP integration currently documents Microsoft 365 support, while the Keycloak documentation states that its token-authentication approach does not currently support Google Mail.

Make sure the From address complies with your SMTP provider's sender policy. Some providers reject unauthorized sender addresses during SMTP submission, while others may accept the message but later fail delivery.

Test the SMTP configuration

In the Admin Console, Test connection sends a test message to the email address of the administrator currently logged in. Make sure that admin account has an email address configured first. A successful test displays SMTP connection successful. E-mail was sent!

The test message is sent to the email address of the currently logged-in administrator, not to an arbitrary address you type into a dialog.

The Admin REST API exposes the same check as POST /admin/realms/{realm}/testSMTPConnection. HTTP 204 from testSMTPConnection means Keycloak completed the SMTP test request successfully. It confirms that Keycloak could connect and submit the test message, but it does not guarantee that the recipient's mail provider will place the message in the inbox. A relay can accept the message and bounce or filter it later.

In this lab, testing against an unreachable relay returned HTTP 500 with {"errorMessage":"Failed to send email"}. Test again after network, TLS, or credential changes.

Test connectivity from a Keycloak container

Keycloak opens the SMTP socket from its own network namespace. A relay that answers on the host loopback is only reachable when the container shares the host network or you point Host at an address the container can route to.

From inside the Keycloak container, confirm that Keycloak can reach the SMTP host and port with Bash built-ins. The tested Keycloak 26.7.3 container did not include nc or openssl, so this lab uses Bash /dev/tcp:

export KC_CONTAINER=keycloak-podman

podman exec "$KC_CONTAINER" sh -c 'timeout 2 bash -c "echo >/dev/tcp/127.0.0.1/1025" && echo port_1025_open"'

Sample output:

port_1025_open

Prove the failure mode on a closed port before you change realm settings:

podman exec "$KC_CONTAINER" sh -c 'timeout 2 bash -c "echo >/dev/tcp/127.0.0.1/19999" 2>&1 || echo connection_refused"'

Sample output:

bash: connect: Connection refused
connection_refused

On the host (or in a debug image with openssl), inspect STARTTLS on a submission port:

openssl s_client -connect smtp.example.com:587 -starttls smtp -brief 2>&1 | head -6

Sample output (trimmed):

CONNECTION ESTABLISHED
Protocol version: TLSv1.3

If TCP fails from the container but works on the host, fix routing or switch Podman to host networking before changing the SSL or StartTLS settings.

SMTP authentication

Keycloak 26.x supports two SMTP authentication choices in the Admin Console:

• Password — username and password authentication
• Token — XOAUTH2; Keycloak obtains an OAuth access token and uses it for SMTP authentication

In REST data, password authentication maps to authType basic. Token authentication enables XOAUTH2.

Username and password

For password-based relays, set Authentication to on and supply the SMTP username and password in the Email tab.

Do not store SMTP passwords in Git or baked container images. Keycloak supports vault-backed values for SMTP password fields, so prefer deployment-time secret injection or a supported vault mechanism.

When you rotate credentials through the Admin REST API, include the authentication fields your provider expects. After rotation, run Test connection again to confirm that email is working.

XOAUTH2 / token authentication

Use Token authentication when your mail provider requires XOAUTH2. Keycloak obtains the SMTP OAuth token using the configured client-credentials settings. Provider-side setup differs significantly, so follow the vendor's SMTP OAuth documentation. Keycloak's current documentation provides a tested Microsoft 365 example. It also notes that Google Mail is not currently compatible with this Client Credentials-based XOAUTH2 implementation.

AWS SES SMTP still expects password authentication, not XOAUTH2.

Send a real verification or password-reset email

After SMTP passes the test, confirm the flows your realm actually uses.

Verify-email through execute-actions-email requires a user with an email attribute. See Create and manage users in Keycloak and Keycloak required actions for user setup and the email trigger.

Password-reset mail uses the same SMTP session when a user submits Forgot Password? on the login form. The forgot-password walkthrough and enumeration-safe UI behavior are documented in Configure forgot password in Keycloak so this page stays focused on SMTP transport.

Common Keycloak SMTP errors

Reproduce a refused connection through the test API:

export KC_BASE='http://127.0.0.1:8080'
export REALM='golinuxcloud'

ADMIN_TOKEN=$(curl -sS -X POST "${KC_BASE}/realms/master/protocol/openid-connect/token" \
  -d 'grant_type=password' -d 'client_id=admin-cli' \
  -d 'username=admin' -d 'password=ChangeMe!2026' | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

curl -sS -w ' HTTP:%{http_code}\n' -X POST \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" -H 'Content-Type: application/json' \
  "${KC_BASE}/admin/realms/${REALM}/testSMTPConnection" \
  -d '{"host":"127.0.0.1","port":"19999","from":"bad@test","ssl":"false","starttls":"false","auth":"false"}'

Sample output:

{"errorMessage":"Failed to send email"} HTTP:500

Investigate JavaMail/SMTP errors in the logs:

export KC_CONTAINER=keycloak-podman

podman logs --tail 20 "$KC_CONTAINER" 2>&1 | grep -iE 'ConnectException|SMTP|Authentication|Failed to send'

Sample output:

Caused by: java.net.ConnectException: Connection refused
	at org.eclipse.angus.mail.smtp.SMTPTransport.openServer(SMTPTransport.java:2193)

If certificate validation fails against a private CA, add that CA to the trust material used by your Keycloak deployment. Full Keycloak truststore configuration is outside this article.

Summary

Keycloak SMTP configuration tells Keycloak how to connect to your mail relay. Configure sender fields, host, port, encryption, and authentication under Realm settings → Email, then use Test connection to confirm that email is working.

Match SSL versus StartTLS to your provider's port guidance, make sure the logged-in admin has an email address before testing, and verify connectivity from the Keycloak container when the relay is unreachable. After SMTP is stable, enable the user-facing flows that send mail and keep relay logs alongside Keycloak events when delivery still fails.

References

• Keycloak Server Administration Guide — Configuring email for a realm
• Keycloak Server Administration Guide — XOAUTH2 email configuration
• Keycloak Admin REST API — RealmAdminResource.testSMTPConnection