Thuê Gmail qua API cho tool: tạo đơn, chờ mã, hủy

Cập nhật 02/10/2026 · 5 phút đọc

Khi cần thuê Gmail lặp lại nhiều lần trong một tool, script hay hệ thống nội bộ, thao tác tay trên web không theo kịp. API của OTPGmail cho phép tự động cả ba việc: tạo đơn thuê, lấy mã khi có, và hủy hoàn tiền khi không cần nữa. Bài này đi qua luồng chuẩn bằng ví dụ curl ngắn gọn, kèm cách xử lý các lỗi hay gặp khi chạy tự động.

Vì sao tool tự động nên gọi trực tiếp API

Gọi API phù hợp khi bạn cần: chạy lại luồng thuê nhiều lần trong CI hoặc theo lịch, xử lý đơn hàng cho nhiều khách mà không có người trực tiếp bấm web, hoặc ghi log chi tiết mã lỗi để tự động xử lý (thử lại, đổi định dạng, cảnh báo số dư thấp). Với vài lượt thuê không thường xuyên, dùng form trên web vẫn nhanh hơn viết code.

Luồng 3 bước

1. Tạo đơn — POST /v1/orders với service và domain (tùy chọn, mặc định gmail.com). Tiền chỉ trừ khi cấp địa chỉ thành công.
2. Chờ và lấy mã — poll GET /v1/orders/{orderId} mỗi 3–5 giây cho tới khi mảng otp có phần tử.
3. Dùng mã hoặc hủy — dùng mã ở dịch vụ đích; nếu đổi ý trước khi có mã, gọi POST /v1/orders/{orderId}/cancel để hoàn tiền ngay, thay vì chờ hệ thống tự hủy sau 25 phút.

Gọi bằng curl

Xác thực bằng header Authorization: Bearer <api_key>, lấy key ở trang Hồ sơ. Đặt sẵn biến BASE trỏ tới địa chỉ gốc của API ghi trong tài liệu API trước khi chạy các lệnh dưới đây.

# 1. Tạo đơn thuê GitHub, định dạng Gmail
curl -s "$BASE/v1/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"service":"git","domain":"gmail.com"}'

# 2. Poll lấy mã (lặp lại mỗi 3-5 giây, thay ORDER_ID)
curl -s "$BASE/v1/orders/ORDER_ID" \
  -H "Authorization: Bearer $API_KEY"

# 3. Hủy đơn nếu chưa có mã và không cần nữa
curl -s -X POST "$BASE/v1/orders/ORDER_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

Phản hồi tạo đơn là một mảng (vì có thể thuê nhiều đơn cùng lúc bằng quantity), mỗi phần tử gồm orderId, email, status, otp: [], codeDeadlineAt, rentExpiresAt. Muốn xem trước giá và tồn kho của từng dịch vụ, gọi GET /v1/services.

Đọc mã và nhận thêm mã

Khi otp có phần tử, lấy phần tử cuối cùng để dùng mã mới nhất. Mã mới được thêm vào cuối otp[] trong khi đơn còn nhận được mã (giới hạn số mã của dịch vụ và thời gian của nguồn hàng vẫn áp dụng; mốc cuối là rentExpiresAt, tính từ lúc thuê); ở phần lớn nguồn hàng không cần gọi lệnh nào thêm, chỉ cần tiếp tục gọi đúng GET /v1/orders/{orderId}. Một nguồn hàng cần gọi POST /v1/orders/{orderId}/next-code để nhận mã kế tiếp — ngoài thời gian không tốn thêm tiền phải gửi confirmFee: true, phí bằng 50% giá thuê và được hoàn nếu 20 phút không có thư mới; hộp thư iCloud riêng dùng POST /v1/orders/{orderId}/rerent để thuê lại cùng hộp thư với 50% giá. Nhiều dịch vụ chỉ gửi một mã cho mỗi hộp thư: khi đó otp[] chỉ có mã đầu. Chi tiết cơ chế này ở bài nhận thêm mã sau khi thuê Gmail.

Xử lý lỗi thường gặp

• NO_MAILS_AVAILABLE (hết kho): không bị trừ tiền, nên thử lại sau vài phút hoặc đổi domain.
• DOMAIN_UNAVAILABLE: dịch vụ không hỗ trợ iCloud hoặc iCloud tạm hết; rơi về gmail.com.
• INSUFFICIENT_BALANCE: cần nạp thêm; tool nên cảnh báo trước khi số dư xuống thấp, không đợi lỗi mới xử lý.
• VALIDATION_ERROR: sai mã dịch vụ hoặc giá trị domain; lấy đúng mã dịch vụ từ GET /v1/services thay vì gõ tay.
• ORDER_NOT_CANCELLABLE: đơn đã có mã, không hủy được nữa — đây là hành vi đúng, không phải lỗi.

Idempotency và giới hạn tốc độ

Luôn gửi header Idempotency-Key với một giá trị mới (UUID) cho mỗi đơn muốn tạo. Nếu request bị timeout và tool của bạn tự động retry, gửi lại đúng key cũ sẽ nhận về đơn đã tạo trước đó thay vì bị tính thêm một đơn mới — quan trọng với tool tự động vì retry là hành vi mặc định của nhiều thư viện HTTP. Giữ khoảng poll 3–5 giây; gọi nhanh hơn không giúp mã về sớm hơn, chỉ làm tool dễ chạm giới hạn tốc độ (RATE_LIMITED).

Muốn xem ví dụ đầy đủ bằng Python và Node.js chạy được ngay, kèm xử lý lỗi chi tiết hơn, đọc bài API nhận OTP qua email cho tool tự động. Cần số lượng lớn ổn định, không cần hoàn tiền theo từng đơn, xem thêm thuê Gmail theo lô: lô mua trên web, còn API dùng để xem lô và đọc mã (GET /v1/batches…), không tạo lô được.

Câu hỏi thường gặp

API có tính phí riêng ngoài giá thuê mỗi đơn không?

Không. Gọi API dùng đúng số dư và đúng giá như thuê qua web, không có phụ phí cho việc dùng API.

Poll bao lâu một lần là hợp lý?

3–5 giây. Hệ thống có giới hạn tốc độ (mặc định tối đa 20 lệnh mỗi giây và 900 lệnh mỗi phút cho mỗi key), và việc kiểm tra hộp thư phía sau cũng có nhịp riêng nên poll nhanh hơn không rút ngắn thời gian có mã.

Không dùng Idempotency-Key thì có sao không?

Vẫn tạo đơn được, nhưng nếu request bị timeout và bạn retry, có thể vô tình tạo thêm một đơn mới bị trừ tiền lần hai. Luôn dùng key này khi gọi từ tool tự động.

Có thể thuê nhiều đơn trong một lần gọi API không?

Có, dùng tham số quantity khi tạo đơn (tối đa 200 hộp thư mỗi lệnh); phản hồi trả về một mảng gồm từng đơn tương ứng.

Lấy API key tại OTPGmail, xem tài liệu đầy đủ ở API, và kiểm tra giá theo dịch vụ tại bảng giá trước khi tích hợp vào tool của bạn.

Bài liên quan