如何获取 Resend API Key 并发出第一封邮件

Resend 是一个为开发者打造的邮件 API：一次 POST 请求、一个 JSON body，就能发出一封事务性邮件。每个请求都需要 API Key，而以什么方式创建这个 Key，决定了它一旦泄露能造成多大的破坏。本指南覆盖完整路径：注册、验证发信域名（或直接使用内置的测试地址）、创建一个权限范围合适的 Key，以及用 curl、Node 和 Python 发出你的第一封邮件。你还会把 Key 存进 Apifox，从而无需把密钥粘贴到 shell 里就能测试接口。

如果你想了解这个 API 在发信之外的整体面貌，Resend API 入门指南里有其余内容。下文所有内容都对照 官方 Resend 文档 核对过，因此其中的数字和错误字符串与你实际看到的完全一致。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

开始前你需要准备什么

• 一个 Resend 账号。本教程用免费版就足够。
• 一个你自己掌控的域名。如果手边没有，第一次发信可以用测试地址。
• 本机装有 curl；如果你想跑 SDK 示例，还需要 Node.js 或 Python。
• 如果你打算跟着做测试部分，需要安装 Apifox。

第 1 步：创建 Resend 账号

在 resend.com 注册并确认你的邮件。记下你注册时使用的地址：在验证域名之前，它是 Resend 唯一会投递测试邮件的收件箱，忘了这一点，你第一天就会遇到最让人摸不着头脑的 403。

第 2 步：验证发信域名，或使用测试地址

两条路线，先从快的那条开始。

路线 A：上手用的测试地址。 Resend 允许你无需任何配置就从 onboarding@resend.dev 发信。限制在收件人：必须是你自己的账号邮箱。发给其他任何人，API 都会返回 403，并附带消息 “You can only send testing emails to your own email address”。

路线 B：你自己的域名。 对于任何正式用途，在控制台的 Domains 下添加域名。Resend 建议使用子域名，例如 notifications.example.com，而不是你的根域名，这样你产品的发信声誉就与公司邮件相互隔离。选择离收件人最近的区域，然后把 Resend 生成的 DNS 记录复制到你的 DNS 服务商。文档把它们描述为“DKIM 和 SPF 配置（TXT 以及 MX 或 CNAME 记录）”。Return-Path 子域名默认为 send.example.com。

验证通常在 15 分钟内完成，不过 DNS 传播最长可能需要 72 小时。如果卡住了，检查两个经典元凶：记录被放在根域名而不是 send 子域名上，以及 Cloudflare 代理（云朵图标必须是灰色，不是橙色）。修好记录后，点击 “Restart verification”。之后再添加一条 DMARC 记录；发信并不强制要求它，但收件箱服务商会因此给你加分。

第 3 步：创建权限范围合适的 API Key

在控制台打开 API keys 页面，点击 Create API Key。有三个字段很关键；创建 API Key 文档对每一个都有说明：

• 名称。最多 50 个字符。按应用和环境来命名，例如 billing-service-prod，这样以后区分不同 Key 会容易得多。
• 权限。“Full access” 可以创建、删除、获取和更新任何资源，包括域名和其他 API Key。“Sending access” 只能发送邮件。任何要部署的东西都选 sending access。full-access 的 Key 只该待在你的笔记本上，或者哪儿都别放。
• 域名。使用 sending access 时，你可以把 Key 限制在一个已验证的域名上。限定到 notifications.example.com 的 Key 无法从 billing.example.com 发信，这就限定了泄露后的影响范围。

Resend 只会展示一次这个 Key。它以 re_ 开头，一旦你关闭对话框，你可以重命名它，但再也无法查看它。请直接把它复制到环境变量里：

export RESEND_API_KEY="re_xxxxxxxxx"

Resend 自己的建议是：Key 永不过期，所以每 90 天或更短时间轮换一次；控制台会标记任何 30 天未使用的 Key；如果某个 Key 泄露，立即删除它，而不是等到下一次轮换。把 re_ 字符串提交到 git 是最常见的泄露途径，所以第一次推送前先对你的仓库跑一次密钥扫描。

你也可以用 POST https://api.resend.com/api-keys 来创建 Key，传入 name、permission（full_access 或 sending_access）以及可选的 domain_id。这个调用需要一个 full-access 的 Key，这也是要让自己只保留一个这种 Key 的又一个理由。

第 4 步：发出你的第一封邮件

发信接口是 POST https://api.resend.com/emails。认证方式是 Authorization header 中的 Bearer token，body 是 JSON，并且只接受 HTTPS。有三个必填字段：from、to 和 subject。可以再加 html、text，或者两者都加；如果只发 html，Resend 会生成纯文本部分。to 接受一个字符串，或最多 50 个地址的数组。完整参数列表见 send email 参考文档。

curl

curl -X POST 'https://api.resend.com/emails' \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@resend.dev>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>"
  }'

调用成功会返回 {"id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}。有一个怪癖：每个请求都必须带 User-Agent header，否则 API 会返回 403，错误码为 1010。curl 和各 SDK 都会自动设置，但跑在 edge runtime 里手写的客户端可能不会。

Node.js

npm install resend

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: 'Acme <notifications@example.com>',
  to: ['you@yourcompany.com'],
  subject: 'First Resend email',
  html: '<p>Your Resend key works.</p>',
});

if (error) {
  console.error(error);
} else {
  console.log(data.id);
}

Node SDK 从不为 API 错误抛异常。它返回 { data, error }，所以在访问 data.id 之前先检查 error。

Python

pip install resend

import os
import resend
from resend.exceptions import ResendError

resend.api_key = os.environ["RESEND_API_KEY"]

params: resend.Emails.SendParams = {
    "from": "Acme <notifications@example.com>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>",
}

try:
    email = resend.Emails.send(params)
    print(email["id"])
except ResendError as err:
    print(err)

Python SDK 则相反：失败时会抛出 ResendError，所以要把发送逻辑包在 try/except 里。

第 5 步：在 Apifox 中存储并测试这个 Key

curl 只能一次性证明这个 Key 可用。Apifox 能把这一次性操作变成团队可以反复运行的东西，并且让 Key 不出现在 shell 历史和聊天记录里。

把 Key 存成 secret 变量。创建一个名为 Resend 的环境，添加 RESEND_API_KEY 变量，并把它标记为 secret，这样它的值在 UI 中会被遮蔽，也不会出现在导出内容里。如果你为每个环境保留不同的仅发信 Key（你应该这么做），环境与 secret 变量指南里有 dev、staging、prod 的拆分做法。

发送请求。创建一个指向 https://api.resend.com/emails 的 POST 请求，把 Auth 设为 Bearer Token，值为 {{RESEND_API_KEY}}，再粘贴 curl 示例里的 JSON body。点击 Send。id 会出现在响应面板里，紧挨着下面提到的限流 header。

把它保存成测试。加两条断言：状态码等于 200，且 $.id 存在。把请求放进测试场景，你就有了一个只要有人改动邮件相关代码就会运行的冒烟测试。让它指向 staging 并使用受域名限制的仅发信 Key，就可以安全地在 CI 中运行。

为前端联调 mock 这个接口。你的前端需要的是响应的数据结构，而不是真的发一封信。在 Apifox 中 mock 这个接口，让它在每次调用时返回 {"id": "mock-email-id"}。UI 团队就可以一直开发“邮件已发送”这个状态，既不会消耗每天 100 封的免费额度，也不会把真实收件箱刷爆。免费版支持 4 名用户。

你会最先撞上的免费额度限制

Resend 定价页 显示免费版每月 3,000 封邮件，每天上限 100 封，可用 3 个域名，数据保留 30 天。Pro 版每月 20 美元起，包含 50,000 封邮件、10 个域名，且没有每日上限，超出部分每 1,000 封 0.90 美元。

发往 resend.dev 地址的测试邮件同样计入这些配额，所以针对 delivered@resend.dev 做压测照样会消耗掉你每天的 100 封。bounced@resend.dev、complained@resend.dev 和 suppressed@resend.dev 可以在不使用真实坏地址的情况下，分别模拟硬退信、垃圾邮件投诉和被抑制的收件人。

除配额之外，速率限制默认是每个团队每秒 10 个请求，由该团队下所有 Key 共享。每个响应都带有 ratelimit-limit、ratelimit-remaining、ratelimit-reset 和 retry-after header，因此发信循环可以在撞上 429 之前先退避。需要更多？Resend 要求你联系支持，而不是创建额外的团队。

常见错误及修复方法

每个失败都会以 JSON 返回，包含 statusCode、name 和 message。下面是你第一天就会遇到的几个，来自 错误参考文档：

一个你确信没写错的 Key 却返回 401，通常意味着变量末尾多了换行符，或者某个 .env 文件从未被加载。从 API 的角度看，这两种情况都像是缺少 Key。

常见问题

创建后还能再次看到我的 Resend API Key 吗？

不能。Resend 只在创建时展示一次该值。如果你弄丢了，就用相同的名称和权限创建一个新 Key，部署它，然后删除旧的。

我应该选 full access 还是 sending access？

sending access，并且限制到一个域名，适用于所有会离开你机器的 Key。保留一个 full-access 的 Key 用于控制台类的操作，比如添加域名或创建其他 Key，并且绝不要把它放进应用里发布。

不验证域名可以测试发信吗？

可以。用 onboarding@resend.dev 作为 from 地址，用你自己的账号邮箱作为收件人。在验证域名之前，发给其他任何收件人都会返回 403。

有没有办法在终端而不是控制台管理 Resend？

有。Resend CLI 指南涵盖安装步骤，以及在不打开浏览器的情况下运行常用的域名和邮件命令。

免费版一天发超过 100 封邮件会怎样？

API 会返回 429 和 daily_quota_exceeded，发送会在每日重置后恢复。如果你经常需要更多，Pro 版取消了这一上限，免费邮件 API 汇总文章里有其他服务商免费额度的对比。

总结

拿到一个 Resend API Key 只要两分钟；把它用对要五分钟。验证一个子域名，创建一个锁定到该域名的仅发信 Key，把它放进环境变量，然后用 curl 发一封邮件确认整条链路。接着把请求搬进 Apifox，保存断言，并 mock 这个接口，这样团队其他成员就能基于它开发，而不用消耗你的配额。发布能满足需求的最小权限 Key。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。

获取专属报价与部署方案

详细的私有化部署系统架构与安全白皮书

针对您公司规模的专属报价单

免费的 1v1 专属产品演示 (Demo) 机会

获取部署方案

* 提交后，我们的客户经理将在 1 个工作日内与您联系

林俊锋 企业微信

@Apifox 专属顾问

扫码备注: 私有化 + 公司名