Lấy mã OTP Gmail qua API từ hộp thư thử của bạn

Nên dùng Gmail API trực tiếp hay API của Mailera?

Nếu bạn chỉ cần đọc mã xác minh Gmail cho một luồng kiểm thử được phép, Mailera có endpoint lấy OTP. Bạn kết nối Gmail qua IMAP bằng mật khẩu ứng dụng, rồi ứng dụng thử gọi REST API của Mailera bằng khoá API.

OTP ở đây là mã xác minh nằm trong email ứng dụng gửi đến hộp thư của bạn. Hướng dẫn tổng quát đọc OTP từ hộp thư của chính bạn trình bày tác vụ này; phần dưới tập trung vào kết nối và xử lý lỗi Gmail.

Với Gmail API, scope quyết định mức truy cập của ứng dụng. Phương thức users.messages.list trả về id và threadId; bạn dùng users.messages.get để lấy thêm nội dung rồi tự xử lý mã.

Kết nối Gmail với Mailera theo cách này dùng mật khẩu ứng dụng, không yêu cầu bạn tạo dự án Google Cloud. Đây là API Mailera, không phải API chính thức của Google. Mailera kết nối các hộp thư bạn đã có để ứng dụng đọc thư qua một API chung.

Cần chuẩn bị gì để kết nối Gmail?

Dùng hộp thư thử nghiệm thuộc quyền sở hữu của bạn. Mật khẩu ứng dụng (app password) khác với mật khẩu đăng nhập Google thông thường.

Theo hướng dẫn mật khẩu ứng dụng của Google, tài khoản phải bật xác minh 2 bước mới dùng được tính năng này. Google khuyến nghị dùng "Sign in with Google" khi ứng dụng hỗ trợ, nhưng Mailera kết nối Gmail qua IMAP bằng mật khẩu ứng dụng, không qua luồng đó. Làm theo hướng dẫn đó để tạo mật khẩu khi tài khoản cho phép; không nhập mật khẩu đăng nhập Gmail vào Mailera.

Bạn có thể không thấy tuỳ chọn mật khẩu ứng dụng nếu tài khoản chỉ dùng khoá bảo mật cho xác minh 2 bước, thuộc tổ chức hoặc bật Advanced Protection. Với tài khoản công ty hay trường học, hãy hỏi quản trị viên thay vì thay đổi bảo mật để tránh chính sách. Hướng dẫn xác minh 2 bước của Google cũng yêu cầu liên hệ quản trị viên khi không thể thiết lập tính năng này.

Trong Mailera, chỉ vai trò Quản trị viên hoặc Trưởng nhóm mới thêm được hộp thư.

Các bước lấy mã OTP Gmail bằng Mailera

1. Thêm hộp thư Gmail

Vào Danh sách hộp thư → Thêm hộp thư, chọn Một hộp thư. Điền Địa chỉ email, kiểm tra nhà cung cấp là Gmail rồi chọn Tiếp tục.

Trong Thông tin kết nối, nhập mật khẩu ứng dụng vào Mật khẩu, chọn Nhóm quản lý, rồi chọn Kiểm tra & kết nối. Mailera đăng nhập thử, không gửi email trong bước kiểm tra này.

Nếu nhận thư được nhưng kiểm tra gửi thất bại, bạn có thể chọn Lưu ở chế độ Chỉ nhận cho tác vụ đọc OTP. Bài kết nối hộp thư đầu tiên với Mailera giải thích chi tiết các bước thêm hộp thư.

2. Tạo khoá chỉ có quyền đọc

Trong Cài đặt, mở phần khoá API và chọn Tạo key. Đặt Tên gợi nhớ, giới hạn Phạm vi hộp thư vào nhóm chứa Gmail thử nghiệm và chỉ cấp quyền read. Không cấp send khi chỉ cần đọc mã.

Chọn Thời hạn phù hợp với đợt kiểm thử. Khi thấy Key đã tạo — sao chép ngay, lưu khoá vào nơi quản lý bí mật và đưa vào biến môi trường $MAILERA_API_KEY. Khoá chỉ hiển thị một lần; không chèn vào mã nguồn.

3. Xác định đúng hộp thư

Gọi danh sách hộp thư:

curl --get 'https://mailera.app/api/public/v1/mailboxes' \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Trong mảng data, đối chiếu email với Gmail thử nghiệm, rồi lưu id tương ứng vào $MAILBOX_ID. Không lấy phần tử đầu tiên chỉ vì nó đứng đầu danh sách. Nếu chưa thấy hộp thư, kiểm tra lại khoá API có đúng phạm vi nhóm chứa hộp thư này không, hoặc phân trang bằng limit, offset.

4. Bắt đầu yêu cầu xác minh

Ghi lại thời điểm bắt đầu, rồi yêu cầu ứng dụng thử gửi email xác minh. Giữ lại người gửi và tiêu đề dự kiến để dùng trong truy vấn.

5. Gọi endpoint OTP với bộ lọc

Ví dụ dưới dùng cửa sổ 5 phút. Thay địa chỉ và tiêu đề minh hoạ bằng giá trị của ứng dụng thử:

curl --get "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/otp" \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'from=verification@example.com' \
  --data-urlencode 'subject=Ma xac minh' \
  --data-urlencode 'since_minutes=5'

Endpoint GET /mailboxes/{id}/otp yêu cầu quyền read. Tài liệu API Mailera là nơi tra cứu endpoint khi nối truy vấn này vào ứng dụng.

6. Đối chiếu thư trước khi dùng mã

Nếu cần xem thư nguồn, gọi danh sách thư với cùng người gửi:

curl --get "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages" \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'folder=inbox' \
  --data-urlencode 'from=verification@example.com'

Đối chiếu from.address, subject và received_at trong kết quả. Muốn đọc nội dung, lấy id của thư làm $MESSAGE_ID rồi gọi GET /mailboxes/{id}/messages/{msgId}; nội dung nằm trong body.text và body.html.

Nếu chưa có mã phù hợp, chờ rồi thử lại. Đặt giới hạn tổng thời gian và tăng khoảng nghỉ giữa các lần gọi; khi hết thời gian, dừng để chẩn đoán thay vì lặp vô hạn.

Làm sao giảm nguy cơ lấy nhầm mã của lần trước?

Đừng chỉ hỏi “mã mới nhất là gì”. Hãy giới hạn đúng hộp thư, người gửi, tiêu đề và khoảng thời gian của yêu cầu vừa tạo.

since_minutes là bộ lọc thời gian, không xác nhận mã còn hạn hoặc thuộc đúng phiên kiểm thử. Chẳng hạn, cửa sổ 5 phút vẫn có thể chứa thư của lần thử trước nếu hai lần diễn ra gần nhau.

So sánh received_at của thư nguồn với thời điểm bắt đầu đã ghi lại. Tránh chạy đồng thời các yêu cầu có cùng người gửi và tiêu đề trên hộp thư này khi chưa có cách phân biệt chúng. Không tự mở rộng cửa sổ thời gian chỉ để truy vấn trả về một mã.

Lỗi hay gặp: vì sao không lấy được mã OTP Gmail?

Kiểm tra theo dấu hiệu. Nếu kết nối đang báo lỗi, xử lý kết nối trước. Nếu hộp thư kết nối được nhưng không thấy email, kiểm tra Thư rác và lần đồng bộ gần nhất.

Endpoint /placement nhận from, subject, since_minutes để kiểm tra thư vào Hộp thư đến hay Thư rác. Với Gmail, GET /mailboxes/{id}/status dựa trên lần đồng bộ gần nhất, không phải một lần đăng nhập trực tiếp ngay lúc gọi.

Bạn có thể xem trường sync.last_synced_at trong thông tin hộp thư (GET /mailboxes/{id}). Mailera điều chỉnh tần suất kiểm tra nền theo mức sử dụng của từng hộp thư, nên mỗi hộp thư có thể có khoảng chờ giữa các lần đồng bộ khác nhau.

Cần bảo vệ mã OTP và khoá API như thế nào?

Chỉ đọc mã từ hộp thư thử của chính bạn trong quy trình được phép. Che địa chỉ riêng tư, OTP, mật khẩu ứng dụng và khoá API trong ảnh chụp hoặc nhật ký; tránh ghi nguyên phản hồi chứa mã vào log kiểm thử.

Giữ khoá ở phạm vi nhóm cần dùng, đặt thời hạn và thu hồi khi kết thúc đợt thử. Trang bảo mật Mailera trình bày thêm về bảo vệ quyền truy cập.

Mailera không tạo hộp thư Gmail hay địa chỉ mới, không bảo đảm thư vào Hộp thư đến hoặc mã xuất hiện tức thì, và không phải đối tác chính thức của Google.