Resend là một API email được xây dựng dành cho các nhà phát triển: một yêu cầu POST, một thân JSON, và một email giao dịch sẽ được gửi đi. Mỗi yêu cầu cần một khóa API, và cách bạn tạo khóa đó quyết định mức độ thiệt hại mà một khóa bị rò rỉ có thể gây ra. Hướng dẫn này sẽ chỉ cho bạn toàn bộ quy trình: đăng ký, xác minh miền gửi (hoặc dựa vào địa chỉ thử nghiệm tích hợp sẵn), tạo khóa với phạm vi quyền phù hợp, và gửi email đầu tiên của bạn bằng curl, Node và Python. Bạn cũng sẽ lưu trữ khóa trong Apidog để có thể kiểm tra điểm cuối mà không cần dán bí mật vào shell của mình.
Nếu bạn muốn có cái nhìn tổng quan hơn về những gì API này làm ngoài việc gửi thư, hướng dẫn dành cho người mới bắt đầu về API Resend sẽ đề cập đến phần còn lại. Mọi thứ dưới đây đều được kiểm tra đối chiếu với tài liệu chính thức của Resend, vì vậy các con số và chuỗi lỗi sẽ khớp với những gì bạn thấy.
Những gì bạn cần trước khi bắt đầu
- Một tài khoản Resend. Gói miễn phí là đủ cho hướng dẫn này.
- Một miền mà bạn kiểm soát. Nếu bạn không có sẵn, địa chỉ thử nghiệm sẽ giúp bạn gửi email đầu tiên.
- curl trên máy của bạn, cộng với Node.js hoặc Python nếu bạn muốn các ví dụ về SDK.
- Apidog đã được cài đặt nếu bạn định làm theo phần kiểm thử.
Bước 1: tạo tài khoản Resend
Đăng ký tại resend.com và xác nhận email của bạn. Ghi lại địa chỉ mà bạn đã đăng ký: cho đến khi bạn xác minh một miền, đó là hộp thư đến duy nhất mà Resend sẽ gửi email thử nghiệm đến, và việc quên điều đó sẽ gây ra lỗi 403 khó hiểu nhất mà bạn sẽ thấy vào ngày đầu tiên.
Bước 2: xác minh miền gửi, hoặc sử dụng địa chỉ thử nghiệm
Có hai cách; hãy bắt đầu với cách nhanh hơn.
Cách A: địa chỉ thử nghiệm onboarding. Resend cho phép bạn gửi từ onboarding@resend.dev mà không cần thiết lập. Vấn đề là người nhận: đó phải là email tài khoản của chính bạn. Gửi cho bất kỳ ai khác và API sẽ trả về lỗi 403 với thông báo “Bạn chỉ có thể gửi email thử nghiệm đến địa chỉ email của chính mình”.
Cách B: miền của riêng bạn. Đối với bất kỳ mục đích thực tế nào, hãy thêm một miền trong bảng điều khiển dưới mục Domains. Resend khuyến nghị sử dụng một tên miền phụ như notifications.example.com thay vì miền gốc của bạn, để danh tiếng gửi thư của sản phẩm của bạn được tách biệt khỏi thư công ty của bạn. Chọn khu vực gần người nhận nhất của bạn, sau đó sao chép các bản ghi DNS mà Resend tạo vào nhà cung cấp DNS của bạn. Tài liệu mô tả chúng là “các cấu hình DKIM và SPF (bản ghi TXT và MX hoặc CNAME)”. Tên miền phụ Return-Path mặc định là send.example.com.
Việc xác minh thường hoàn tất trong vòng 15 phút, mặc dù việc lan truyền DNS có thể mất tới 72 giờ. Nếu quá trình này bị kẹt, hãy kiểm tra hai nguyên nhân cổ điển: các bản ghi được đặt trên miền gốc thay vì tên miền phụ send, và proxy Cloudflare (biểu tượng đám mây phải màu xám, không phải màu cam). Sửa các bản ghi, sau đó nhấp vào “Restart verification”. Thêm bản ghi DMARC sau đó; nó không bắt buộc để gửi, nhưng các nhà cung cấp hộp thư đến đánh giá cao điều này.
Bước 3: tạo khóa API với phạm vi phù hợp
Mở trang API keys trong bảng điều khiển và nhấp vào Create API Key. Ba trường quan trọng; tài liệu tạo khóa API đề cập đến từng trường:
- Name. Tối đa 50 ký tự. Đặt tên cho ứng dụng và môi trường, ví dụ:
billing-service-prod, để các khóa dễ phân biệt sau này. - Permission. “Full access” (Toàn quyền truy cập) có thể tạo, xóa, lấy và cập nhật bất kỳ tài nguyên nào, bao gồm các miền và các khóa API khác. “Sending access” (Quyền gửi) chỉ có thể gửi email. Chọn quyền gửi cho bất kỳ thứ gì đã triển khai. Khóa toàn quyền truy cập thuộc về máy tính xách tay của bạn, hoặc không ở đâu cả.
- Domain. Với quyền gửi, bạn có thể giới hạn khóa chỉ cho một miền đã xác minh. Một khóa được giới hạn cho
notifications.example.comkhông thể gửi từbilling.example.com, điều này hạn chế phạm vi thiệt hại nếu khóa bị rò rỉ.
Resend chỉ hiển thị khóa đúng một lần. Nó bắt đầu bằng re_, và một khi bạn đóng hộp thoại, bạn có thể đổi tên khóa nhưng không bao giờ xem lại được nữa. Sao chép nó trực tiếp vào một biến môi trường:
export RESEND_API_KEY="re_xxxxxxxxx"
Hướng dẫn của Resend: khóa không bao giờ hết hạn, vì vậy hãy xoay vòng chúng cứ sau 90 ngày hoặc sớm hơn; bảng điều khiển sẽ gắn cờ bất kỳ khóa nào không được sử dụng trong 30 ngày; và nếu một khóa bị rò rỉ, hãy xóa nó ngay lập tức thay vì chờ đến lần xoay vòng tiếp theo. Việc cam kết các chuỗi re_ vào git là con đường rò rỉ phổ biến nhất, vì vậy hãy chạy một máy quét bí mật trên các repo của bạn trước lần đẩy đầu tiên.
Bạn cũng có thể tạo khóa bằng POST https://api.resend.com/api-keys, truyền name, permission (full_access hoặc sending_access), và một domain_id tùy chọn. Cuộc gọi đó cần một khóa toàn quyền truy cập, một lý do nữa để chỉ giữ chính xác một khóa đó.
Bước 4: gửi email đầu tiên của bạn
Điểm cuối gửi là POST https://api.resend.com/emails. Xác thực là một mã thông báo Bearer trong tiêu đề Authorization, thân là JSON, và chỉ chấp nhận HTTPS. Ba trường là bắt buộc: from, to, và subject. Thêm html, text, hoặc cả hai; nếu bạn chỉ gửi html, Resend sẽ tạo phần văn bản thuần túy. to nhận một chuỗi hoặc một mảng lên đến 50 địa chỉ. Danh sách tham số đầy đủ có trong tham chiếu gửi 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>"
}'
Một cuộc gọi thành công trả về {"id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}. Một điểm kỳ lạ: mỗi yêu cầu phải mang một tiêu đề User-Agent, nếu không API sẽ trả lời 403 với mã 1010. curl và các SDK thiết lập một cái; một client tự viết trong một môi trường biên có thể không.
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);
}
SDK Node không bao giờ ném lỗi cho các lỗi API. Nó trả về { data, error }, vì vậy hãy kiểm tra error trước khi chạm vào data.id.
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)
SDK Python làm ngược lại: nó ném ResendError khi thất bại, vì vậy hãy bọc các lần gửi trong try/except.
Bước 5: lưu trữ và kiểm tra khóa trong Apidog
Curl chứng minh khóa hoạt động một lần. Apidog biến lần duy nhất đó thành thứ mà nhóm của bạn có thể chạy lại, và giữ khóa khỏi lịch sử shell và nhật ký trò chuyện.
Lưu khóa dưới dạng biến bí mật. Tạo một môi trường có tên Resend, thêm RESEND_API_KEY làm biến, và đánh dấu nó là bí mật để giá trị được che giấu trong giao diện người dùng và không được xuất. Hướng dẫn về môi trường và biến bí mật bao gồm việc chia tách dev, staging và prod nếu bạn giữ một khóa chỉ gửi khác nhau cho mỗi môi trường, điều mà bạn nên làm.
Gửi yêu cầu. Tạo một yêu cầu POST tới https://api.resend.com/emails, đặt Auth thành Bearer Token với {{RESEND_API_KEY}}, và dán thân JSON từ ví dụ curl. Nhấn Gửi. id sẽ hiển thị trong bảng phản hồi bên cạnh các tiêu đề giới hạn tỷ lệ được đề cập bên dưới.
Lưu nó dưới dạng một thử nghiệm. Thêm hai xác nhận: trạng thái bằng 200 và $.id tồn tại. Đặt yêu cầu vào một kịch bản thử nghiệm và bạn có một thử nghiệm smoke test chạy bất cứ khi nào ai đó chạm vào mã email. Chỉ nó đến staging với một khóa gửi bị giới hạn miền và nó an toàn để chạy từ CI.
Giả lập điểm cuối cho công việc frontend. Frontend của bạn cần hình dạng phản hồi, không phải là một lần gửi thực sự. Giả lập điểm cuối trong Apidog để nó trả về {"id": "mock-email-id"} trong mỗi cuộc gọi. Nhóm UI có thể xây dựng trạng thái "email đã gửi" cả ngày mà không cần chạm vào hạn ngạch miễn phí 100 email mỗi ngày hoặc gửi thư rác vào hộp thư thực. Tải Apidog để thiết lập điều này; gói miễn phí bao gồm bốn người dùng.
Giới hạn gói miễn phí mà bạn sẽ gặp trước tiên
Trang định giá của Resend liệt kê gói miễn phí là 3.000 email mỗi tháng, giới hạn 100 email mỗi ngày, với 3 miền và lưu trữ dữ liệu 30 ngày. Gói Pro bắt đầu từ 20 đô la mỗi tháng cho 50.000 email, 10 miền và không giới hạn hàng ngày, với phí vượt mức là 0,90 đô la cho mỗi 1.000 email.
Email thử nghiệm đến các địa chỉ resend.dev được tính vào hạn ngạch đó, vì vậy một bài kiểm tra tải nhắm vào delivered@resend.dev vẫn tiêu tốn 100 email hàng ngày của bạn. bounced@resend.dev, complained@resend.dev, và suppressed@resend.dev mô phỏng một hard bounce, một khiếu nại spam, và một người nhận bị chặn mà không cần địa chỉ xấu thực sự.
Ngoài hạn ngạch, giới hạn tỷ lệ mặc định là 10 yêu cầu mỗi giây cho mỗi nhóm, được chia sẻ giữa mọi khóa trong nhóm. Mỗi phản hồi mang các tiêu đề ratelimit-limit, ratelimit-remaining, ratelimit-reset, và retry-after, vì vậy một vòng lặp gửi có thể lùi lại trước khi gặp lỗi 429. Cần nhiều hơn? Resend yêu cầu bạn liên hệ hỗ trợ thay vì tạo thêm nhóm.
Các lỗi thường gặp và cách khắc phục
Mỗi lỗi sẽ trả về JSON với statusCode, name, và message. Đây là những lỗi bạn sẽ gặp vào ngày đầu tiên, từ tham chiếu lỗi:
| Trạng thái | Tên | Điều gì đã xảy ra | Cách khắc phục |
|---|---|---|---|
| 401 | missing_api_key |
Không có tiêu đề Authorization |
Thêm Authorization: Bearer re_... |
| 401 | restricted_api_key |
Khóa chỉ gửi được sử dụng trên điểm cuối không phải gửi | Sử dụng khóa toàn quyền truy cập cho cuộc gọi đó |
| 403 | validation_error |
“Miền chưa được xác minh” | Hoàn tất xác minh DNS, hoặc sửa địa chỉ from |
| 403 | validation_error |
Địa chỉ thử nghiệm được gửi cho người khác ngoài bạn | Gửi đến email tài khoản của bạn, hoặc xác minh một miền |
| 403 | restricted_api_key |
“Khóa API không hoạt động” | Khóa đã bị xóa; tạo một khóa mới |
| 422 | missing_required_field |
Thiếu from, to, hoặc subject |
Kiểm tra thân so với tham chiếu |
| 429 | rate_limit_exceeded |
Vượt quá 10 yêu cầu mỗi giây | Xếp hàng gửi, tuân thủ retry-after |
| 429 | daily_quota_exceeded |
Vượt quá 100 email hôm nay trên gói miễn phí | Chờ đến khi đặt lại hoặc nâng cấp |
Lỗi 401 với một khóa mà bạn chắc chắn là đúng thường có nghĩa là có một dòng mới thừa trong biến hoặc một tệp .env chưa bao giờ được tải. Cả hai đều trông giống như một khóa bị thiếu từ phía API.
Câu hỏi thường gặp
Tôi có thể xem lại khóa API Resend của mình sau khi tạo không?
Không. Resend chỉ hiển thị giá trị một lần tại thời điểm tạo. Nếu bạn mất nó, hãy tạo một khóa mới với cùng tên và quyền, triển khai nó, sau đó xóa khóa cũ.
Tôi nên chọn toàn quyền truy cập hay quyền gửi?
Quyền gửi, giới hạn cho một miền, cho mọi khóa rời khỏi máy của bạn. Giữ một khóa toàn quyền truy cập cho các công việc kiểu bảng điều khiển như thêm miền hoặc tạo các khóa khác, và không bao giờ đưa nó vào một ứng dụng.
Tôi có thể kiểm tra việc gửi mà không cần xác minh miền không?
Có. Sử dụng onboarding@resend.dev làm địa chỉ from và email tài khoản của chính bạn làm người nhận. Bất kỳ người nhận nào khác sẽ trả về lỗi 403 cho đến khi một miền được xác minh.
Có cách nào để quản lý Resend từ terminal thay vì bảng điều khiển không?
Có. Hướng dẫn sử dụng Resend CLI bao gồm cách cài đặt nó và chạy các lệnh miền và email thông thường mà không cần mở trình duyệt.
Điều gì xảy ra khi tôi vượt quá 100 email mỗi ngày trên gói miễn phí?
API trả về 429 với daily_quota_exceeded, và việc gửi sẽ tiếp tục sau khi đặt lại hàng ngày. Nếu bạn thường xuyên cần nhiều hơn, gói Pro sẽ loại bỏ giới hạn, và tổng hợp các API email miễn phí cho thấy các gói miễn phí của các nhà cung cấp khác so sánh như thế nào.
Tóm lại
Lấy khóa API Resend mất hai phút; thực hiện đúng mất năm phút. Xác minh một tên miền phụ, tạo một khóa chỉ gửi được khóa vào miền đó, giữ nó trong một biến môi trường và gửi một email bằng curl để xác nhận quá trình hoàn tất. Sau đó chuyển yêu cầu vào Apidog, lưu các xác nhận và giả lập điểm cuối để phần còn lại của nhóm bạn có thể xây dựng dựa trên nó mà không tốn hạn ngạch của bạn. Hãy gửi khóa có ít quyền hạn nhất nhưng vẫn hoàn thành công việc.