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.
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.
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.451or452: 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.