电子邮件账户显示“凭据无效”或SMTP/IMAP认证错误

当您保存电子邮件账户，或者当 Frappe 通过某个电子邮件账户发送和接收邮件时，邮件服务器可能会拒绝登录。您会看到保存错误、电子邮件账户被禁用，或者邮件卡在队列中。

错误信息

根据登录被拒绝的位置，您会看到以下其中一种情况：

保存时，来自发送服务器

Incorrect Configuration
Invalid credentials for Email Account

Incorrect Configuration
Invalid Outgoing Mail Server or Port: Connection unexpectedly closed

在计划同步时，来自接收服务器

Authentication failed while receiving emails from Email Account: <name>.
Message from server: b'[AUTHENTICATIONFAILED] Invalid credentials (Failure)'
</name>

来自第三方 SMTP 中继，出现在错误日志中

smtplib.SMTPSenderRefused: (502, b'5.7.0 Please authenticate first', ...)

保存时对话框的样子——冒号后面的措辞取决于拒绝连接的对象。

这四种情况含义相同：服务器不接受您提供的登录 ID 和密码。具体措辞取决于失败发生在保存时（发送）还是计划同步期间（接收），以及您的服务商如何报告该问题。

为什么会发生这种情况

当您保存电子邮件账户时，Frappe 会使用您输入的登录 ID、密码、服务器、端口和加密方式（TLS 或 SSL）连接到邮件服务器，并尝试进行身份验证。只有当所有这些都与服务器期望的一致时，服务器才会接受登录。密码错误、端口与加密方式不匹配，或者服务商不再允许使用普通密码的登录流程（Gmail 和 Microsoft 现在都要求这样做），都会返回同一种拒绝。

如果电子邮件账户之前一直正常工作，后来开始失败，通常的原因是服务商那边更改了密码，或者启用了双重身份验证（2FA），这会使 Frappe 等应用使用的账户密码失效。

如何修复

1. 检查基本设置

  1. 打开电子邮件账户，滚动到身份验证部分（服务器字段则在发送（SMTP）设置中）。
  2. 如果账户登录所用的地址与发送时使用的地址不同，请勾选使用不同的电子邮件 ID，并在备用电子邮件 ID中输入真实的登录信息。
  3. 重新输入密码。复制粘贴的密码可能带有尾部空格或换行符，从而导致与密码错误相同的错误。
  4. 对照服务商公布的信息，检查发送服务器（或电子邮件服务器）和端口。
  5. 检查使用 TLS和使用 SSL——只应勾选其中一项，并且必须与端口匹配：
  • 端口 587 → 勾选使用 TLS，取消勾选使用 SSL。
  • 端口 465 → 勾选发送使用 SSL，取消勾选使用 TLS。

在同一端口下两项都勾选或两项都不勾选，本身就是导致此错误的常见原因。

发送（SMTP）设置——使用 TLS 和端口已用方框标出，这是最常出现不匹配的一对设置。

如果使用 TLS和使用 SSL呈灰色且无法更改，说明该电子邮件账户已关联到一个电子邮件域。发送设置来自该电子邮件域，而不是来自账户。请打开关联的电子邮件域进行更改，或者清除电子邮件账户上的域字段，以便改为在那里解锁这些字段。

2. 适用于 Gmail 或 Google Workspace

Google 不再接受您的普通账户密码用于 Frappe 或任何非 Google 产品的应用。将服务设置为GMail——这会自动填入 IMAP/SMTP 服务器、端口和加密方式——然后使用以下其中一种方式：

将服务设置为 GMail 会预设服务器、端口和加密方式。

  • 应用专用密码。在 myaccount.google.com/security 为 Google 账户开启两步验证，然后在同一页面生成应用专用密码，并将其用作电子邮件账户的密码，而不是您的登录密码。应用专用密码只有在开启两步验证后才有效。如果 2FA 未开启，Google 不会允许您生成应用专用密码，账户会继续拒绝普通密码。
  • OAuth，如果您完全不想存储密码。这需要在 Google Cloud 中设置一个已连接应用，并将其选为电子邮件账户的身份验证方法。设置流程与 Microsoft Office365 电子邮件 OAuth 相同——一个已连接应用、一个重定向 URI，以及用于 IMAP 和 SMTP 的邮件作用域。

3. 适用于第三方 SMTP 服务商（SMTP2Go、Brevo、Sendgrid 等）

这些服务商完全不使用您的电子邮件收件箱密码。它们会签发自己的 SMTP 用户名和 API 密钥，与任何账户登录信息分开：

  1. 在服务商的控制面板中，找到（或生成）用于发送邮件的SMTP 用户名和SMTP 密码 / API 密钥。例如，对于 Sendgrid，SMTP 用户名就是 apikey，密码是生成的 API 密钥，而不是账户密码。
  2. 在电子邮件账户上，勾选使用不同的电子邮件 ID，并在其中输入服务商的 SMTP 用户名。
  3. 将 API 密钥输入为密码。
  4. 请完全按照提供商文档中的说明输入传出服务器和端口，并与第 1 步中该端口对应的 使用 TLS / 使用 SSL 设置保持一致。

如果你专门使用 Brevo，并且在匹配上述所有设置后仍然遇到 (502, b'5.7.0 Please authenticate first')，你的站点可能需要 smtp_no_ehlo_after_auth 站点配置键——某些中继会拒绝 Python 的 SMTP 客户端在登录后发送的额外 EHLO 命令。从 Frappe v16.17.0 起，此问题已默认修复。在更早的版本上，请提交支持工单并引用此错误。

4. 在 Frappe 之外测试凭据

在再次保存电子邮件账户之前，请先确认登录本身可以正常工作：

  • 在你的电子邮件客户端（Outlook、Thunderbird、Gmail 或 Outlook 网页应用）中，使用相同的服务器、端口、加密方式和密码添加同一账户。如果在那里也失败，则问题出在凭据或提供商，而不是 Frappe。

  • 如果你有 shell 访问权限，请直接测试 SMTP 登录：

    openssl s_client -connect smtp.gmail.com:587 -starttls smtp

    然后输入 EHLO、AUTH LOGIN，以及 base64 编码的登录 ID 和密码。返回 235 响应表示登录成功。返回 535 或 534 响应表示服务器拒绝了登录。

一旦登录在 Frappe 之外可以正常工作，请返回电子邮件账户并使用相同的值再次保存。

检查失败后发生了什么

登录失败并不总是立即以对话框形式显示。请检查以下两个位置：

  • 电子邮件队列：打开电子邮件队列列表并按 状态 = 错误 筛选。打开失败的行，查看服务器针对该特定电子邮件返回的拒绝消息。
  • 错误日志：如果电子邮件账户被自动禁用（在计划同步中反复出现身份验证失败后会发生这种情况），请在错误日志列表中搜索其被禁用时间附近的完整回溯信息，然后在修复凭据后重新启用该电子邮件账户。

如何预防

  • 为 Gmail 和 Microsoft 账户开启双重验证并改用应用密码（或 OAuth），以免在提供商强制更改之前措手不及。
  • 当提供商的密码或 API 密钥轮换时，请在同一天更新电子邮件账户——过期的密码会使账户保持禁用状态，并悄无声息地停止通知、欢迎电子邮件和警报。

如果这不能解决问题

如果登录在 Frappe 之外成功，但在电子邮件账户上仍然失败，请提交支持工单并附上：确切的错误文本、电子邮件账户名称，以及失败发生在 保存、传出发送还是 传入同步时。

  • 电子邮件账户
  • 电子邮件域
  • 在 ERPNext 中设置 Sendgrid SMTP 电子邮件
  • Microsoft Office365 电子邮件 OAuth