使用Node.js与mailgun.js调用Mailgun时遭遇401未授权错误

问题说明 #

使用mailgun.js@10.2.1版本，严格遵循官网示例代码实现邮件发送流程：已注册免费Mailgun账号、生成API密钥、使用已验证的收件人邮箱，但始终返回权限错误：

[Error: Unauthorized] { status: 401, details: 'Forbidden', type: 'MailgunAPIError' }

排查与解决步骤 #

1. 确认API密钥的有效性与类型 #

• 免费沙箱账号仅支持私有API密钥（以key-开头），公钥（pubkey-开头）仅用于Webhook验证，无法用于发送邮件，直接排除公钥的使用。
• 核对密钥是否在Mailgun后台「Security > API Keys」页面生成，确保选中的是「Secret API Key」选项。

2. 核对沙箱域名与发件人地址 #

• mg.messages.create的第一个参数必须是你账号下的沙箱域名（格式为sandboxxxxx.mailgun.org），需与Mailgun后台「Sending > Domains」中的沙箱域名完全一致，不能存在字符拼写错误。
• 发件人from字段必须使用沙箱域名下的邮箱，格式为自定义名称 <mailgun@你的沙箱域名>，例如你的沙箱域名为sandbox8dcd8ea3cce6409487a1093460a9d27a.mailgun.org，则发件人需为Excited User <mailgun@sandbox8dcd8ea3cce6409487a1093460a9d27a.mailgun.org>，不能使用其他域名的邮箱。

3. 验证密钥的配置正确性 #

• 若使用环境变量process.env.MAILGUN_API_KEY，先通过console.log(process.env.MAILGUN_API_KEY)确认变量是否正确加载，避免环境变量未配置或名称拼写错误。
• 若直接硬编码密钥，确保复制的是完整的密钥字符串，无多余空格、换行符等无效字符。

4. 确认收件人邮箱的验证状态 #

• 免费沙箱账号仅允许发送到已验证的收件人邮箱，需在Mailgun后台「Sending > Authorized Recipients」页面确认收件人邮箱已显示「Verified」状态，未验证的邮箱会触发权限拦截。

5. 检查API客户端配置细节 #

• mailgun.client配置中的username必须固定为'api'，这是Mailgun API的强制要求，不能修改为其他值。
• 排查是否存在代理、防火墙拦截请求，导致API密钥无法正确传递至Mailgun服务器，可尝试在无代理的本地环境测试。

6. 测试简化版代码排除干扰 #

使用最简化的代码测试，排除其他代码逻辑的干扰：

const formData = require('form-data');
const Mailgun = require('mailgun.js');
const mailgun = new Mailgun(formData);

// 替换为你的私有密钥和沙箱域名
const mg = mailgun.client({username: 'api', key: 'key-你的完整私有密钥'});

mg.messages.create('sandbox-你的沙箱域名.mailgun.org', {
  from: "Test Sender <mailgun@sandbox-你的沙箱域名.mailgun.org>",
  to: ["已验证的收件人邮箱地址"],
  subject: "Test Email",
  text: "This is a test email from Mailgun"
})
.then(msg => console.log('邮件发送成功:', msg))
.catch(err => console.error('发送失败:', err));

若以上步骤均无法解决问题，可查看Mailgun后台「Logs > API Requests」中的请求日志，里面会提供更详细的错误原因。

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