Cho agent trình duyệt chờ mã xác minh email rồi tiếp tục

Đây là bước lấy mã xác minh từ email, không phải kiểm tra một địa chỉ email có hợp lệ hay không. OTP là mã dùng một lần; tìm thấy mã trong thư chưa đủ để kết luận mã thuộc lần xác minh đang mở.

Mailera kết nối hộp thư sẵn có với ứng dụng và agent. Nếu bạn cần phần nền tảng về cách đọc mã, xem đọc OTP từ hộp thư của chính bạn; phần dưới tập trung vào điểm dừng và điều kiện tiếp tục phiên trình duyệt.

Cần chuẩn bị gì trước khi agent đến bước nhập mã?

Chỉ dùng ứng dụng và hộp thư thử bạn sở hữu hoặc được phép kiểm thử. Kết nối hộp thư theo hướng dẫn thêm hộp thư vào Mailera, rồi kiểm tra đúng hộp thư và trạng thái kết nối trong Danh sách hộp thư.

Trong Cài đặt, mở phần khóa API và chọn Tạo key. Đặt Phạm vi hộp thư vào nhóm hộp thư thử, chỉ cấp quyền read. Khóa mới chỉ hiện một lần: lưu ở phía máy chủ, không đưa vào trang web hay nội dung hội thoại của agent.

Lưu trạng thái trong ứng dụng, không chỉ trong ngữ cảnh mô hình. Mỗi lượt cần có định danh phiên, hộp thư, trang đang mở, thời điểm yêu cầu mã và hạn chờ. Bảng dưới là thiết kế trạng thái cho ứng dụng của bạn, không phải trạng thái API Mailera:

Đặt trước dấu hiệu thành công của ứng dụng thử, chẳng hạn một trang đích hoặc trạng thái xác minh cụ thể. Đừng để mô hình tự suy đoán rằng biểu mẫu biến mất nghĩa là đã xong.

Tạm dừng, lấy mã và tiếp tục theo những bước nào?

1. Ghi nhận yêu cầu mã và giữ phiên. Khi kịch bản đến bước gửi mã, lưu thời điểm yêu cầu. Giữ nguyên phiên trình duyệt và trang nhập mã; không tạo lượt trình duyệt mới chỉ để tiếp tục. Khóa các thao tác tiếp theo cho đến khi nhánh xác minh kết thúc.
2. Tìm mã trong đúng hộp thư. GET /mailboxes/{id}/otp lấy OTP mới nhất với quyền read. Dùng from, subject và since_minutes để thu hẹp kết quả.

Ví dụ sau dùng cửa sổ tìm kiếm 5 phút, không phải thời hạn hiệu lực của mã. Thay người gửi và tiêu đề bằng giá trị của ứng dụng thử; đặt $MAILERA_API_KEY và $MAILBOX_ID ở môi trường máy chủ:

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

3. Đối chiếu thư với lượt đang chờ. Bộ lọc tìm mã không chứng minh mã thuộc đúng lần yêu cầu. Khi cần đối chiếu, gọi GET /mailboxes/{id}/messages với folder và from phù hợp. Trong ứng dụng, kiểm tra mailbox_id, from.address, subject và đối chiếu received_at trong dữ liệu trả về với thời điểm yêu cầu mã đã lưu; lấy id của thư cần đọc làm $MESSAGE_ID.

curl "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Nội dung thư nằm trong data.body.text và data.body.html. Đối chiếu thêm dấu hiệu của lượt xác minh nếu ứng dụng thử có cung cấp. Thời điểm nhận mới hơn chỉ là một điều kiện chọn thư, không thay thế việc xác định đúng lượt. Nếu còn nhiều thư phù hợp mà không phân biệt được, chuyển cho người vận hành.

4. Chờ có giới hạn nếu chưa có mã phù hợp. Đặt khoảng nghỉ tăng dần giữa các lần đọc, nhưng không vượt hạn chờ. Kiểm tra hạn trước mỗi lần gọi và trước khi nhập mã, kể cả khi phản hồi vừa trả về. Không liên tục yêu cầu gửi lại mã. Nếu cho phép gửi lại, hãy coi đó là lượt yêu cầu mới và cập nhật trạng thái tương ứng.
5. Chỉ chuyển dữ liệu cần cho bước nhập. Bộ điều phối chọn mã rồi đưa mã cho thao tác nhập liệu đã định. Không đưa toàn bộ email vào lời nhắc để agent tự quyết định phải làm gì. Ghi nhận thư đã dùng để không chọn lại trong cùng lượt.
6. Kiểm tra kết quả trên trang. Nhập xong chưa phải xác minh thành công. Chỉ mở khóa bước tiếp theo khi thấy dấu hiệu thành công đã định. Nếu mã bị từ chối, phiên hết hạn hoặc trang đổi bất thường, dừng hoặc chuyển sang nhánh phục hồi được phê duyệt trước.

Với Browser Use, kho mã chính thức mô tả cách đăng ký hàm bằng Tools rồi truyền cho agent. Bạn có thể đặt lời gọi Mailera trong công cụ tùy chỉnh; logic giữ phiên và quyết định tiếp tục vẫn thuộc ứng dụng. Đừng coi đồng bộ hồ sơ là bản sao đầy đủ của phiên: Browser Use nêu rõ tính năng này chuyển cookies, không chuyển local storage, IndexedDB hoặc extensions.

Nên dùng REST API hay MCP cho bước chờ mã?

Ưu tiên REST khi bạn đang viết bộ điều phối riêng: điều kiện chờ và chuyển trạng thái nằm rõ trong mã ứng dụng. MCP phù hợp khi môi trường agent đã có cơ chế gọi công cụ.

Trang dành cho nhà phát triển giới thiệu các cách tích hợp. Tài liệu REST API là nơi tra endpoint; trang MCP của Mailera dành cho kết nối công cụ.

Theo đặc tả công cụ MCP, client dùng tools/list để khám phá công cụ, đọc inputSchema rồi gọi bằng tools/call. Đọc lược đồ thực tế của get_latest_otp, không suy ra tham số MCP từ tên tham số REST.

Đặc tả cũng khuyến nghị giới hạn thời gian gọi công cụ và kiểm tra kết quả trước khi chuyển cho mô hình. Hạn của từng lời gọi không thay thế hạn chờ của cả lượt xác minh. Dù dùng REST hay MCP, hãy giữ quyết định tiếp tục trong mã điều phối có thể kiểm thử.

Những lỗi hay gặp khi agent chờ email là gì?

Các endpoint trong bảng dùng phương thức GET và quyền read. Không cấp thêm sync hoặc move chỉ để đọc OTP. Nếu cần đồng bộ hay chuyển thư, tách thành quy trình có quyền và kiểm soát riêng.

Khi chạy song song, gắn từng lượt chờ với phiên và hộp thư rõ ràng. Nếu các lượt dùng chung hộp thư mà không có dấu hiệu phân biệt thư, đừng để chúng cùng lấy “mã mới nhất”.

Làm sao để agent đọc thư mà không làm theo lệnh trong thư?

Thư đến là dữ liệu không tin cậy, không phải lệnh cho agent. Một email có thể chứa chỉ dẫn yêu cầu đổi trang, tiết lộ khóa hoặc thực hiện hành động ngoài kịch bản. Bộ đọc chỉ trích dữ liệu cần thiết; nội dung thư không được thay đổi quyền hay mục tiêu của agent.

Giữ khóa trong nhóm hộp thư thử với quyền read, không cấp send cho luồng chỉ lấy mã. Yêu cầu xác nhận trước khi gửi thư hoặc thực hiện hành động nhạy cảm ngoài phạm vi kiểm thử đã phê duyệt. Thông tin bảo mật Mailera cung cấp thêm bối cảnh khi bạn thiết kế quyền truy cập.

Không tự mở mọi liên kết trong email. Nếu kịch bản dùng liên kết xác minh, kiểm tra tên miền và điểm đến theo danh sách cho phép, đồng thời kiểm tra lại khi có chuyển hướng. Điểm đến không khớp thì dừng.

Che OTP, khóa API, địa chỉ cá nhân và liên kết chứa bí mật trong ảnh lẫn nhật ký. Nhật ký chẩn đoán nên lưu trạng thái, mốc thời gian và lý do dừng thay vì toàn bộ nội dung thư.

Mailera làm gì và không làm gì trong luồng này?

Mailera cung cấp quyền đọc hộp thư đã kết nối, endpoint lấy OTP và công cụ MCP tương ứng. Mailera không tạo hộp thư hay địa chỉ email mới. Trong luồng này, hãy để ứng dụng điều phối quản lý phiên trình duyệt và chỉ tiếp tục khi trang đích xác nhận thành công.

Mailera không bảo đảm thư nằm trong Hộp thư đến và không vượt qua bộ lọc spam. Hãy thiết kế nhánh hết thời gian chờ để ứng dụng dừng hoặc chuyển cho người vận hành, thay vì để agent tự ứng biến.