Tới nội dung chính
Mail9inbox

Cho developer

Một API email tạm để bộ test của bạn trỏ vào

Tạo địa chỉ bằng code, đợi thư thật qua một luồng trực tiếp, và đọc mã xác minh ra từ một trường dữ liệu thay vì từ một biểu thức chính quy bạn viết lúc nửa đêm.

cURL
# 1. Tạo địa chỉ
curl -X POST https://9inbox.io/api/v1/addresses \
  -H "Authorization: Bearer mgw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "9inbox.io"}'

# 2. Đọc thư đã tới
curl "https://9inbox.io/api/v1/messages?address_id=<uuid>&limit=50" \
  -H "Authorization: Bearer mgw_live_xxx"
Node.js
const headers = { Authorization: `Bearer ${process.env.NINEINBOX_KEY}` };

const res = await fetch("https://9inbox.io/api/v1/addresses", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const { data } = await res.json();
console.log(data.address.address); // [email protected]
SSE realtime
// Thư đến đẩy thẳng về, không cần polling.
const stream = new EventSource(
  `https://9inbox.io/api/v1/messages/stream?address_id=${id}`,
);

stream.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  // otp_code đã được server trích sẵn — không phải tự regex thân thư.
  console.log(msg.subject, msg.otp_code);
});

Vì sao cần API

Vấn đề mà nó thật sự giải quyết

Kiểm thử một luồng đăng ký từ đầu đến cuối nghĩa là phải kiểm thử cả đoạn có một email thật đi tới. Các đội thường né bằng một trong ba cách, và cả ba đều không ổn: giả lập bước gửi thư rồi thôi không test nó nữa, dồn mọi thư về một hộp thư dùng chung rồi tranh nhau xem thư nào của ai, hoặc tạo hộp thư thật bằng tay rồi lặng lẽ ngừng chạy bài test đó sau vài tháng.

Một địa chỉ tạo được bằng một request và đọc được bằng một request nữa xoá bỏ chỗ né đó. Bài test tạo địa chỉ, điền form đăng ký bằng nó, đợi trên luồng cho tới khi thư xác minh tới, rồi đọc mã ra từ thân response. Không có trạng thái dùng chung giữa các lần chạy, vì mỗi lần chạy tự nghĩ ra địa chỉ của mình, và không cần script dọn dẹp, vì địa chỉ tự hết hạn.

Điểm đáng nói là trường otp_code. Mã xác minh được trích khỏi thư ở phía chúng tôi và trả về ngay trong bản tóm tắt thư. Nghĩa là bài test của bạn không phải mang theo một biểu thức chính quy cần sửa mỗi lần nhà cung cấp nào đó đổi mẫu email — mà trên thực tế đó chính là thứ làm hỏng loại test này nhiều nhất.

Endpoint

Phần bề mặt bạn sẽ thật sự dùng

POST /api/v1/addresses

Tạo một địa chỉ, có thể chỉ định domain hoặc tự đặt phần tên. Trả về bản ghi địa chỉ đầy đủ. Không gửi phần tên thì server tự sinh tên ngẫu nhiên mười hai ký tự. Domain premium cần gói trả phí.

GET /api/v1/messages

Liệt kê thư của một địa chỉ, hoặc của mọi địa chỉ bạn sở hữu nếu bỏ trống address_id. Phân trang bằng cursor — không có OFFSET ở bất cứ đâu trong API này.

GET /api/v1/messages/:id

Trả về thư đầy đủ, gồm phần HTML đã sanitize, phần văn bản thuần và thông tin tệp đính kèm. Gọi endpoint này tự đánh dấu thư đã đọc.

GET /api/v1/messages/:id/raw

File .eml gốc, dùng khi bạn cần soi header, kết quả DKIM, hay đúng cấu trúc MIME mà người gửi tạo ra.

GET /api/v1/messages/stream

Luồng server-sent events. Phát sự kiện ready kèm danh sách address_id đang theo dõi, sự kiện message mang bản tóm tắt đầy đủ cho mỗi thư mới, và ping mỗi 25 giây để proxy không cắt kết nối.

GET /api/v1/domains

Các domain khả dụng theo gói của bạn, kèm thông tin domain nào là premium và domain nào đang nhận địa chỉ mới.

Giới hạn

Hạn mức, xác thực và những dòng chữ nhỏ

Xác thực bằng bearer token: gửi API key trong header Authorization. Key chỉ hiện đúng một lần lúc tạo và chỉ được lưu dưới dạng hash, nên key bị lộ thì phải thu hồi chứ không lấy lại được. Mỗi key mang scope riêng, và bạn nên phát một key riêng cho từng môi trường để thu hồi key CI bị lộ không kéo theo cả production.

Hạn mức tính theo key và theo phút: sáu mươi request mỗi phút ở gói Pro, sáu trăm ở Business, và sáu mươi mỗi giờ ở gói tài khoản miễn phí. Vượt hạn mức sẽ nhận HTTP 429 kèm header Retry-After tính bằng giây — hãy tôn trọng nó thay vì thử lại ngay, bởi một vòng lặp thử lại dồn dập sẽ giữ bạn ở trạng thái bị chặn vô thời hạn.

Có hai tính chất của luồng SSE cần thiết kế bao quanh. Nó không phát lại: thư tới đúng lúc đang kết nối lại sẽ không sinh ra sự kiện nào, nên một bài test không được phép bỏ sót thư thì phải đối chiếu bằng một lời gọi liệt kê sau khi kết nối, thay vì tin hoàn toàn vào luồng. Và hub chủ động bỏ sự kiện với client quá chậm, nên một bên tiêu thụ chậm sẽ mất sự kiện chứ không làm nghẽn mọi client khác trên cùng một instance.

Webhook có ở gói Pro và Business. Payload được ký bằng HMAC trong header X-MailGW-Signature và thử lại năm lần có backoff. Hãy kiểm tra chữ ký trước khi parse thân request, và làm handler idempotent — một lần thử lại sau timeout sẽ giao cùng một sự kiện tới hai lần.

Câu hỏi của developer

Những thứ hay gặp trong quá trình tích hợp.

Có. Tài khoản miễn phí đã đăng ký được dùng API với sáu mươi request mỗi giờ, đủ để phát triển và đủ cho một lần chạy test đêm quy mô nhỏ. Gói khách vãng lai hoàn toàn không có API, vì không có key nào để xác thực.

Địa chỉ của bạn vẫn đang chờ

Không phải cài gì, không phải điền gì. Cuộn lên đầu trang, bấm Sao chép, rồi dán vào chỗ đang hỏi email của bạn.

Quay lại hộp thư của tôiTạo tài khoản miễn phí