Lập trình20 tháng 3, 2026 · 6 min read

Hướng Dẫn Bắt Đầu Với DustMail API

API của DustMail cho phép bạn tự động hóa việc tạo hòm thư email tạm thời và nhận thư điện tử. Điều này cực kỳ hoàn hảo cho việc viết test tự động, tích hợp vào CI/CD pipelines, và xây dựng các ứng dụng bảo mật. Hướng dẫn này sẽ đi qua tất cả các endpoint quan trọng kèm theo ví dụ thực tế có thể sao chép trong cURL, Node.js và Python để bạn có thể bắt đầu trong chưa đầy 5 phút.

Xác thực (Authentication)

Tất cả các yêu cầu API đều yêu cầu một API Key. Bạn có thể tạo khóa này từBảng điều khiển của bạn, sau đó truyền nó qua tiêu đề Authorization:

Authorization: Bearer dm_live_your_api_key

Ngoài ra, bạn cũng có thể truyền khóa này qua tiêu đề X-API-Key. Khóa API chỉ hiển thị một lần duy nhất lúc khởi tạo và được chúng tôi lưu trữ dưới dạng băm SHA-256 bảo mật - nếu bạn làm mất khóa, bạn sẽ cần tạo một khóa mới.

Tạo hộp thư (Creating an Inbox)

Gửi một yêu cầu POST để tạo một địa chỉ email tạm thời mới:

POST https://dustmail.net/api/v1/inbox

Bạn có thể tùy chọn tên hòm thư (username) tùy ý trong phần body của request nếu khóa API của bạn thuộc tài khoản Premium. Khóa Premium cũng được chọn tên miền tùy thích từ danh sách tên miền của bạn. Với tài khoản Free, địa chỉ email ngẫu nhiên dạng [email protected] sẽ được tạo mặc định.

Ví dụ với cURL

curl -X POST https://dustmail.net/api/v1/inbox \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"duration": 30}'

Ví dụ với Node.js

const res = await fetch('https://dustmail.net/api/v1/inbox', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.DUSTMAIL_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ duration: 30 }),
});
const inbox = await res.json();

Ví dụ với Python

import os, requests
r = requests.post(
  'https://dustmail.net/api/v1/inbox',
  headers={'Authorization': f'Bearer {os.environ["DUSTMAIL_KEY"]}'},
  json={'duration': 30},
)
inbox = r.json()

Kiểm tra thư mới (Polling for Emails)

Sau khi tạo hòm thư, bạn thực hiện gọi API để kiểm tra xem có thư mới gửi đến hay chưa:

GET https://dustmail.net/api/v1/inbox/YOUR_INBOX_ID

Kết quả trả về chứa cả phiên bản văn bản thuần túy (text) và HTML của mỗi email, cùng với thông tin người gửi và thời gian nhận. Tần suất kiểm tra lý tưởng nhất là khoảng 5-10 giây một lần.

Liệt kê và dọn dẹp hộp thư

Sử dụng GET /api/v1/inbox để liệt kê toàn bộ các hòm thư đang hoạt động thuộc khóa API của bạn, và sử dụng lệnh DELETE /api/v1/inbox/{id} để chủ động xóa bỏ hòm thư sớm hơn thời hạn. Khi chạy các kịch bản test tự động, bạn nên: tạo hộp thư ở hook chuẩn bị (setup), thực hiện test, và xóa hộp thư đó ở hook dọn dẹp (teardown).

Giới hạn cuộc gọi (Rate Limits)

Tài khoản miễn phí nhận được tối đa 100 cuộc gọi API mỗi ngày. Hạn ngạch này hoàn toàn đủ cho các dự án cá nhân nhỏ hoặc kiểm thử cơ bản. Các tài khoản Premium nhận được không giới hạn cuộc gọi API - nâng cấp tại trang Bảng giá.

Kịch bản sử dụng (Use Cases)

Khuyến nghị thực hành tốt nhất (Best Practices)

Hãy bảo vệ API Key giống như mật khẩu. Đừng bao giờ commit chúng lên Git. Hãy kéo chúng từ các biến môi trường (environment variables) hoặc secret manager và thường xuyên đổi khóa định kỳ.

Chọn thời hạn ngắn nhất có thể. Hộp thư tồn tại càng lâu sẽ tích trữ dữ liệu càng nhiều và tính vào quota hòm thư đang hoạt động của bạn. Đối với quy trình xác thực thông thường, thời hạn 5 đến 15 phút là đã quá dư dả.

Luôn chủ động dọn dẹp. Mặc dù hòm thư có chế độ tự hủy, việc gọi lệnh DELETE ngay khi test xong giúp giải phóng tài nguyên hệ thống và hạn ngạch của bạn lập tức.

Tài liệu đầy đủ

Để xem hướng dẫn tham chiếu đầy đủ bao gồm cấu trúc request/response chi tiết và nhiều ví dụ mã nguồn hơn, hãy truy cập Tài liệu API của chúng tôi.

Sẵn sàng xây dựng ứng dụng?

Tạo API key của bạn và bắt đầu tích hợp trong vài phút.

Lấy API Key ngay →