Lấy mã OTP Outlook qua API cho quy trình kiểm thử

Bạn cần đọc mã trong thư hay tạo và gửi OTP?

Nếu ứng dụng thử đã gửi mã xác minh đến Outlook, việc cần làm là đọc mã trong thư đó rồi đưa lại cho ứng dụng. Đây là luồng đọc OTP, khác với dịch vụ phát hành mã.

Mailera kết nối Outlook.com, Hotmail và Microsoft 365 qua Microsoft Graph. Endpoint /otp trong bài là API của Mailera. Khi đọc email Outlook bằng Microsoft Graph, thao tác liệt kê thư trả về các đối tượng thư, không theo cấu trúc phản hồi của endpoint OTP này.

Bài này tập trung vào Outlook và Microsoft 365. Với luồng không phụ thuộc nhà cung cấp, xem hướng dẫn đọc OTP từ hộp thư của bạn.

Cần chuẩn bị gì trước khi gọi API?

Bạn cần một hộp thư thử nghiệm do mình sở hữu và ứng dụng có thể gửi thư xác minh đến đó. Dùng hộp thư riêng cho kiểm thử giúp bạn đối chiếu thư mà không đưa thư cá nhân vào luồng tự động.

1. Kết nối hộp thư Microsoft bằng OAuth

Mở Danh sách hộp thư → Thêm hộp thư, chọn thẻ Đăng nhập Microsoft, rồi hoàn tất đăng nhập và đồng ý cấp quyền tại Microsoft. Chỉ vai trò Admin hoặc Leader mới có thể thêm hộp thư.

Mailera không dùng mật khẩu ứng dụng (app password) để kết nối hộp thư Microsoft. Tài liệu uỷ quyền của Microsoft giải thích bước đăng nhập và yêu cầu người dùng đồng ý với các quyền ứng dụng đề nghị.

Trang kết nối Outlook và Microsoft 365 mô tả phương thức kết nối này. Nếu bạn đang thiết lập workspace lần đầu, xem thêm các bước kết nối hộp thư đầu tiên.

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ớ, chọn nhóm hộp thư thử nghiệm tại Phạm vi hộp thư và chỉ cấp quyền read. Luồng đọc mã không cần quyền send.

Khi thấy Key đã tạo — sao chép ngay, lưu khoá vào kho bí mật của môi trường kiểm thử. Giá trị khoá chỉ được hiển thị một lần. Đặt thời hạn phù hợp với công việc thay vì để khoá tồn tại lâu hơn nhu cầu.

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

Nạp khoá vào biến môi trường $MAILERA_API_KEY, rồi gọi:

curl --silent --show-error \
  "https://mailera.app/api/public/v1/mailboxes" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Trong mảng data, đối chiếu email với hộp thư thử của bạn và lấy id tương ứng. Lưu giá trị đó vào $MAILBOX_ID; không mặc định chọn phần tử đầu tiên. Nếu nghi ngờ kết nối, gọi GET /mailboxes/{id}/status để kiểm tra trực tiếp khả năng đăng nhập hộp thư Microsoft.

Gọi API lấy mã OTP Outlook theo những bước nào?

1. Bắt đầu lần kiểm thử và lưu mốc thời gian bắt đầu ở phía ứng dụng.
2. Yêu cầu ứng dụng gửi một thư xác minh mới đến hộp thư đã chọn.
3. Gọi endpoint OTP với bộ lọc phù hợp.
4. Đối chiếu thư trước khi đưa mã vào bước xác minh.

Endpoint yêu cầu quyền read và dùng header Authorization: Bearer $MAILERA_API_KEY. Các thành phần cần chú ý:

Ví dụ dưới đây đặt since_minutes=5. Thay otp@example.com và tiêu đề bằng thông tin của ứng dụng thử:

curl --silent --show-error --get \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/otp" \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode "from=otp@example.com" \
  --data-urlencode "subject=Ma xac minh thu nghiem" \
  --data-urlencode "since_minutes=5" \
  --output otp-response.json

Lệnh lưu phản hồi vào tệp thay vì in mã ra terminal. Tệp vẫn chứa thông tin nhạy cảm: không đưa vào Git, nhật ký hoặc tệp đính kèm của báo cáo kiểm thử; xoá khi xử lý xong.

Khi chưa có kết quả phù hợp, để ứng dụng chờ rồi thử lại trong thời hạn của bài kiểm thử. Hết thời hạn thì dừng và ghi nhận thất bại, không lặp vô hạn. Không tự động yêu cầu gửi mã mới ở mỗi lượt đọc vì sẽ khó xác định thư nào thuộc yêu cầu nào.

Tài liệu API Mailera là nơi tra endpoint và tham số khi triển khai. Trang Mailera dành cho nhà phát triển giới thiệu các cách đưa API vào ứng dụng.

Làm sao tránh lấy nhầm mã từ thư cũ?

Mã mới nhất trong hộp thư chưa chắc là mã của lần thử hiện tại. Hãy chọn đúng hộp thư, lọc theo người gửi và tiêu đề, rồi đối chiếu thời điểm nhận thư với mốc bắt đầu lần thử; đừng chỉ dựa vào việc API trả về một mã.

Nên tránh chạy đồng thời các lần thử có cùng bộ lọc trên một hộp thư nếu bạn không có cách phân biệt chúng.

Khi cần đối chiếu, dùng GET /mailboxes/{id}/messages. Endpoint này có các tham số folder, from và since. Trong kết quả, xem from.address, subject, received_at và id. Đối chiếu thời điểm nhận thư với mốc bắt đầu lần thử thay vì chỉ nhìn phần xem trước.

Sau khi chọn đúng thư, đặt id của thư vào $MESSAGE_ID và đọc nội dung:

curl --silent --show-error \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --output message-response.json

Nội dung nằm trong data.body.text và data.body.html. Bảo vệ tệp này như tệp phản hồi OTP. Bước kiểm thử chỉ hoàn tất khi ứng dụng phát hành chấp nhận mã, không phải ngay khi đọc được mã từ thư.

Lỗi hay gặp: vì sao chưa lấy được mã OTP?

Phân biệt lỗi truy cập hộp thư với trường hợp đọc được hộp thư nhưng chưa thấy thư phù hợp. Hai tình huống này cần kiểm tra theo hướng khác nhau.

Để kiểm tra vị trí thư, gọi GET /mailboxes/{id}/placement với cùng bộ lọc from, subject, since_minutes. Bạn cũng có thể mở Thư rác của đúng hộp thư trên giao diện. Việc kiểm tra vị trí thư là một bước riêng với việc gọi endpoint OTP.

Mailera nhận thư Microsoft mới qua Graph change notifications và có kiểm tra nền định kỳ dự phòng. Nếu cần đồng bộ thủ công, POST /mailboxes/{id}/sync yêu cầu quyền sync riêng. Đừng thêm quyền này vào khoá đọc chỉ để thử xem lỗi có hết không.

Cần giữ an toàn thế nào khi tự động đọc mã xác minh?

Chỉ dùng hộp thư thử của chính bạn. Che mã OTP, địa chỉ cá nhân, liên kết xác minh, khoá API và token trong ảnh chụp cũng như báo cáo lỗi. Nhật ký nên ghi bước thất bại, không ghi toàn bộ phản hồi chứa mã.

Giữ khoá ở phía máy chủ hoặc kho bí mật của môi trường kiểm thử. Giới hạn khoá vào nhóm hộp thư cần dùng và thu hồi khi không còn nhu cầu. Xem thêm thông tin bảo mật Mailera khi thiết lập luồng truy cập.

Nếu AI agent tham gia xử lý, coi nội dung thư là dữ liệu không tin cậy, không phải lệnh. Agent không được làm theo yêu cầu trong thư để đổi cấu hình, gửi khoá hoặc chuyển mã sang nơi khác. Giữ quyền tối thiểu, yêu cầu xác nhận trước thao tác gửi và không cấp send cho luồng chỉ đọc. Bài dùng API email cho AI agent trình bày luồng đọc và thao tác thư rộng hơn.

Giới hạn của Mailera trong luồng OTP

Mailera đọc mã từ thư đã nhận; ứng dụng phát hành quyết định mã còn hiệu lực hay không. Mailera không tạo hộp thư hoặc địa chỉ email mới, không bảo đảm thư nằm trong Hộp thư đến. Chuyển một thư khỏi Thư rác cũng không bảo đảm thư tiếp theo của người gửi sẽ vào Hộp thư đến.