Keycloak新用户注册时未发送邮件的问题排查求助

一、确认注册触发邮件的核心规则 #

• Keycloak默认仅在开启邮箱验证强制要求时，才会在注册后发送验证邮件。检查Realm Settings >> Login页面的Require Email Verification选项是否启用：
  • 若未开启，注册用户状态直接为启用，不会触发邮件发送；
  • 若需无验证但发送欢迎邮件，需自定义注册流程或事件监听器添加邮件动作。

二、验证邮件模板与手动测试 #

• 进入Realm Settings >> Email，确认Verification Email模板存在且内容完整，空模板会导致邮件无法生成；
• 手动触发邮件测试：找到已注册用户，进入Users >> 目标用户 >> Actions >> Send Verify Email，若Mailhog能收到，说明注册流程的触发逻辑有问题；若仍收不到，回到邮件基础配置排查。

三、检查用户状态与邮箱信息 #

• 确认用户邮箱字段：进入Users >> 目标用户 >> Attributes，检查email字段是否填写正确，无拼写错误；
• 查看Email Verified状态：若该字段已为true，Keycloak不会重复发送验证邮件。

四、深层邮件配置校验 #

• 再次验证邮件连接：在Realm Settings >> Email点击Test Connection，确保Docker容器内的配置生效（Mac环境下容器访问本地Mailhog需用host.docker.internal代替localhost，确认配置地址一致）；
• 检查发件人地址：确认Email配置中的From字段已填写，部分邮件服务（含Mailhog）会拒绝无发件人地址的请求。

五、调整日志级别排查细节 #

• 默认日志未记录邮件发送详情，通过以下方式开启DEBUG级日志：
  • 启动Docker容器时添加环境变量：-e KEYCLOAK_LOG_LEVEL=org.keycloak.email:DEBUG
  • 或在Admin Console的Realm Settings >> Logging中，将Email日志级别设为DEBUG
• 重新注册用户后，执行docker logs <keycloak-container-id>查看日志，确认是否有邮件发送的具体记录（如模板渲染、发送请求等）。

六、自定义注册流程添加邮件动作（非验证场景） #

• 若无需邮箱验证但需发送注册欢迎邮件，修改注册流程：
  1. 进入Authentication >> Flows，找到Registration流程；
  2. 点击Add execution，选择Send Email动作并设为Required；
  3. 配置该动作关联的邮件模板（可自定义或复用现有模板）；
  4. 保存流程后重新测试注册。

内容的提问来源于stack exchange，提问作者hotmeatballsoup