Keycloak execute-actions-email Admin API无法发送邮件求助

核心排查步骤 #

1. 核实用户基础状态 #

• 确认用户在Keycloak中处于Enabled状态，禁用用户不会触发邮件发送
• 检查用户的Email Verified字段是否为true，部分Realm配置会强制要求邮箱验证后才能发送重置密码邮件（可在Authentication > Required Actions中确认是否开启该规则）

2. 校验API请求参数 #

• 确保请求体中actions参数包含UPDATE_PASSWORD，正确的请求体示例：

  {
    "actions": ["UPDATE_PASSWORD"],
    "lifespan": 86400
  }
  

• 确认realm和user id参数完全正确，避免请求到错误的Realm或不存在的用户

3. 查看Keycloak服务器日志 #

• 开启org.keycloak.email模块的DEBUG日志，日志会记录邮件发送的全流程，包括是否触发发送、SMTP交互细节、错误信息
• 修改日志配置（keycloak.conf或standalone.xml）开启调试：

  log-level=org.keycloak.email=DEBUG
  

• 日志路径通常为keycloak/logs/keycloak.log，重点排查是否有SMTP发送失败的报错

4. 检查邮件模板与邮箱端过滤 #

• 进入Realm Settings > Email，确认Reset Password模板存在且格式正常，模板损坏可能导致邮件发送失败
• 直接用Realm设置中的测试邮件功能给该用户发测试邮件，确认邮件能正常接收，排除用户邮箱将邮件归为垃圾邮件或拦截的情况

5. 排查异步发送队列与扩展干扰 #

• 若Keycloak配置了异步邮件发送，检查队列是否积压或配置错误，导致邮件延迟发送
• 确认是否安装了第三方邮件扩展或插件，这类组件可能干扰默认的邮件发送逻辑

6. 确认客户端权限配置（若指定了client_id） #

• 若请求中带了client_id，确认该客户端未被禁用，且Valid Redirect URIs配置正确（虽然链接无效不影响邮件发送，但部分场景会触发静默失败）

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