Skip to content

Documentation

Send Keycloak email through Mailtruss.

Keycloak sends account emails from a realm's SMTP settings. Enter the relay once per realm.

Before you start

You need a verified sending domain (see Domains) and an API key (under API keys in the dashboard; it is shown once). For SMTP the key is the password, and a sending-only key is enough. Keep the key in an environment variable on your server, never in code that runs in a browser or an app.

The realm's email settings

In the Keycloak admin console, open the realm, then Realm settings, then the Email tab. Menu names differ slightly between Keycloak versions. Enter these values and save.

Realm settings, Email tab
From: hello@yourdomain.com (a verified domain)
From display name: Acme
Host: smtp.mailtruss.com
Port: 587
Encryption: Enable StartTLS
Authentication: Enabled
Username: mailtruss
Password: <your Mailtruss API key>

Per realm

Email settings belong to each realm, so repeat this for every realm that should send mail. You can use one API key for all of them, or one per realm so you can revoke them separately.

Try it without sending real mail

The Email tab has a Test connection button that sends a message to your admin user's address. The message appears under Emails in the Mailtruss dashboard.

If the test fails
535 the API key is wrong or revoked
550 the from address is not on a verified domain

See what happened

Open the message under Emails in the dashboard: it shows the recorded timeline, what each event proves, and a diagnosis if something went wrong. Mail sent over SMTP appears there like any other message. To be told as it happens, add a webhook.

If it fails

The relay answers with a reply code:

  • 535: the API key is wrong or revoked. Fix the password.
  • 550: refused for good (unverified domain, suppressed recipient, invalid message). Do not retry; the reply says why.
  • 552: too large, or the monthly limit is reached.
  • 451 or 452: temporary (rate limit, daily limit, or a brief problem on our side). Retry later; mail servers do this automatically.

Problems that happen after a message is accepted (bounces, complaints) are explained under delivery errors.

Other guides

Last updated

Something wrong or unclear on this page?

Report an issue