Skip to main content

Email Providers

The authenticator supports four email providers. You choose one per authentication flow and can enable automatic fallback to Keycloak SMTP.

Supported Providers​

ProviderDescriptionRequirements
Keycloak SMTP (Default)Uses Keycloak's built-in SMTP configRealm SMTP settings configured
SendGridSendGrid cloud email serviceAPI key + verified sender
AWS SESAmazon Simple Email ServiceIAM credentials + verified identity
MailgunMailgun email deliveryAPI key + sending domain

Configure Provider​

  1. Navigate to Authentication → Flows
  2. Select your custom flow with the Email OTP authenticator
  3. Click ⚙️ next to Email OTP
  4. Set the provider and credentials (see options below)
Email Provider: KEYCLOAK
Enable Fallback to Keycloak SMTP: true

No credentials needed — uses Realm Settings → Email.

Fallback Mechanism​

When Enable Fallback to Keycloak SMTP is on:

  • If the primary provider fails, the system automatically retries via Keycloak's realm SMTP
  • Ensures delivery even when a 3rd-party service is temporarily unavailable
  • Fallback events are logged for monitoring

:::tip Best practice Always enable fallback in production. Configure realm SMTP as the safety net regardless of which primary provider you use. :::

Troubleshooting​

Emails are not being delivered​

1. Verify realm SMTP first

Before blaming the provider integration, confirm the base SMTP configuration works:

  1. Realm Settings → Email → click "Test connection"
  2. A test email is sent to the admin account — if this fails, fix SMTP before proceeding

2. Enable Simulation Mode temporarily

In the OTP authenticator settings, set Simulation mode to true. Codes will appear in the Keycloak server logs instead of being sent:

docker logs keycloak | grep "SIMULATION MODE"
# ***** SIMULATION MODE ***** Email code send to user@example.com is: 123456

If codes appear in the logs, Keycloak is running correctly — the problem is with the email provider configuration.

3. Check Keycloak logs for provider errors

docker logs keycloak 2>&1 | grep -i "email\|provider\|sendgrid\|ses\|mailgun"

Provider-specific issues​

SymptomLikely causeFix
403 ForbiddenSender not verifiedVerify sender identity in SendGrid dashboard
401 UnauthorizedInvalid API keyRegenerate key with Mail Send permission
Emails land in spamNo domain authenticationSet up domain authentication (SPF/DKIM) in SendGrid

For issues not covered here, see the Troubleshooting guide or open an issue.