Thanks to visit codestin.com
Credit goes to Github.com

Skip to content

Improved documentation for running the keycloak test mail server locally. #46183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ruchikajha95 wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Improved documentation for running the keycloak test mail server locally. #46183

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f63e968
Improved documentation for running the keycloak test mail server loca…
ruchikajha95 Feb 10, 2026
d1da388
Fixed some points on document.
ruchikajha95 Feb 10, 2026
2eeecd6
Review
ahus1 Feb 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 72 additions & 10 deletions docs/tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,20 +106,82 @@ Once started copy/paste the totp secret and press enter. To use a new secret jus
Mail server
-----------

To start a test mail server for testing email sending run:
The Keycloak testsuite includes a standalone mock mail server for testing email-related features such as email verification,
password reset, and other email notifications.

mvn exec:java -Pmail-server

or run org.keycloak.testsuite.MailServer from your favourite IDE!
**Prerequisite:**

- Keycloak server running (see [Keycloak server](#keycloak-server) section above)

### Running the Mail Server

To start the embedded test mail server for local development and testing:

Start the mail server:

```
./mvnw -f testsuite/utils/pom.xml exec:java -Pmail-server
```

or run `org.keycloak.testsuite.MailServer` from your favourite IDE!

The mail server will start on `localhost:3025` and display all received emails in the console.

### Configuring Keycloak

To configure Keycloak to use the test mail server:

1. Open your browser and login to the Keycloak Admin Console with admin credentials.

2. Select the realm you want to configure from the realm dropdown in the top-left corner (e.g., `master` or your test
realm).

3. In the left sidebar, navigate to **Realm settings**.

4. Click on the **Email** tab.

6. Enter the following SMTP configuration values:

| Field | Value | Description |
|-------|---------------------|------------------------------|
| From | `[email protected]` | Email address used as sender |
| Host | `localhost` | Mail server hostname |
| Port | `3025` | Mail server port |

7. Configure optional settings:
- **Enable StartTLS**: Check this box (Yes), or leave it unchecked (No)
- **Enable Authentication**: Leave unchecked (No)
- **Enable SSL**: Leave unchecked (No)

8. Click **Save** to apply the configuration.

9. Optional Test: Configure an email address for the admin user if not configured already. Then return to the **Email** tab and click **Test connection** to verify the mail server is reachable. You should see a success message and the test email
will appear in the mail server console output.

### Testing Email Features

Once configured, you can test various email-related features:

- **Email Verification**:
1. In **Realm settings** → **Login** tab, enable "Verify email".
2. Register a new user or update an existing user's email.
3. Check the mail server console for the verification email.

- **Password Reset**:
1. In **Realm settings** → **Login** tab, enable "Forgot password".
2. Go to the login page and click "Forgot Password?".
3. Enter a user's email and check the mail server console.

To configure Keycloak to use the above server, enter the following values in the realm configuration in the tab **Email**:
- **Update Email**:
1. Change a user's email address in the Account Console.
2. If email verification is enabled, check the mail server console for the confirmation email.

| Field | Value |
|-------|-------------------|
| From | [email protected] |
| Host | localhost |
| Port | 3025 |
- **Event Notifications**:
1. Configure email event listeners in **Realm settings** → **Events**
2. Trigger events and check the mail server console for notifications.

All emails sent by Keycloak will be captured by the test mail server and displayed in the console output with full
content including subject, recipient, and message body.

LDAP server
-----------
Expand Down