---
title: "Đọc mã OTP từ email qua API cho luồng kiểm thử"
description: "Đọc OTP từ hộp thư thử nghiệm qua API Mailera với quyền read, lọc người gửi và tiêu đề, tránh lấy mã cũ và kiểm tra thư gốc khi cần."
url: https://mailera.app/blog/doc-ma-otp-tu-email-qua-api
published: 2026-10-25
updated: 2026-10-25
---

# Đọc mã OTP từ email qua API cho luồng kiểm thử

Dùng hộp thư thử nghiệm sẵn có, khoá chỉ có quyền đọc và bộ lọc phù hợp để lấy mã xác minh. Trước khi đưa mã vào bài kiểm thử, cần đối chiếu đúng lượt yêu cầu thay vì chỉ lấy mã mới nhất.

## Đọc OTP qua API khác gì tạo và xác thực OTP?

OTP là mã dùng một lần trong luồng xác minh. Khi kiểm thử xác minh email, bạn cần đưa mã từ đúng thư vào đúng yêu cầu đang chờ, không phải tự tạo một mã thay thế.

[Mailera kết nối các hộp thư bạn đã có](https://mailera.app/product) với ứng dụng qua REST API, MCP và webhook. Trong luồng này, Mailera phụ trách đọc thư; ứng dụng của bạn vẫn phụ trách phát hành và kiểm tra mã.

| Việc cần làm | Bên phụ trách | Kết quả cần kiểm tra |
| --- | --- | --- |
| Tạo và gửi OTP | Hệ thống xác thực của ứng dụng thử nghiệm | Yêu cầu xác minh đã được khởi tạo |
| Đọc OTP từ hộp thư | Mailera qua API | Mã được trích từ thư phù hợp |
| Xác thực OTP | Ứng dụng đích | Mã được chấp nhận cho đúng yêu cầu |

Chỉ thực hiện quy trình dưới đây với hộp thư thử nghiệm của chính bạn và luồng xác minh bạn kiểm soát. Không dùng khoá truy cập hộp thư của người khác.

## Cần chuẩn bị hộp thư và quyền truy cập nào?

Chuẩn bị một hộp thư riêng cho kiểm thử, rồi nhờ người có vai trò Admin hoặc Leader thêm hộp thư vào Mailera. Đường dẫn trong giao diện là **Danh sách hộp thư → Thêm hộp thư**. [Hướng dẫn kết nối hộp thư đầu tiên](https://mailera.app/blog/cach-ket-noi-email-voi-mailera) trình bày đầy đủ các bước nếu bạn chưa kết nối lần nào.

Với Outlook hoặc Microsoft 365, chọn **Đăng nhập Microsoft** để kết nối bằng OAuth, không dùng mật khẩu ứng dụng. Xem [cách kết nối Microsoft với Mailera](https://mailera.app/providers/microsoft). Về phía Microsoft, [tài liệu truy cập Graph thay mặt người dùng](https://learn.microsoft.com/en-us/graph/auth-v2-user) giải thích việc lấy access token từ Microsoft identity platform.

Với Gmail, Mailera dùng mật khẩu ứng dụng (app password). [Tài liệu mật khẩu ứng dụng của Google](https://support.google.com/accounts/answer/185833) yêu cầu tài khoản bật xác minh 2 bước. Phần cấu hình dành cho Mailera nằm ở [trang kết nối Gmail](https://mailera.app/providers/gmail); không thay mật khẩu ứng dụng bằng mật khẩu đăng nhập thông thường.

Thao tác **Kiểm tra & kết nối** thử kết nối mà không gửi thư. Nếu nhận thư hoạt động nhưng kết nối gửi thất bại, bạn có thể chọn **Lưu ở chế độ Chỉ nhận**. Tác vụ đọc OTP không cần gửi thư từ hộp thư đó.

Tiếp theo, vào **Cài đặt**, mở phần khoá API và chọn **Tạo key**:

1. Đặt **Tên gợi nhớ** để nhận ra khoá của bộ kiểm thử.
2. Giới hạn **Phạm vi hộp thư** vào nhóm hộp thư thử nghiệm.
3. Chỉ cấp quyền `read` cho tác vụ đọc OTP.
4. Đặt **Thời hạn** phù hợp với thời gian sử dụng.
5. Lưu khoá vào kho bí mật hoặc biến môi trường của tiến trình kiểm thử.

Khoá mới chỉ được hiển thị một lần. Không đưa khoá vào mã chạy trên trình duyệt, kho mã nguồn hoặc nhật ký CI. [RFC 6750 về Bearer token](https://www.rfc-editor.org/info/rfc6750/) yêu cầu bảo vệ token khi lưu trữ và truyền tải; thông tin về bảo mật sản phẩm nằm ở [trang bảo mật Mailera](https://mailera.app/security).

![Cấu hình khoá API chỉ có quyền đọc và giới hạn trong nhóm hộp thư thử nghiệm.](https://mailera.app/media/eafacf074562dcd3/doc-ma-otp-tu-email-qua-api-cho-luong-kiem-thu-read-only-key-vi-1200.jpg)
_Tác vụ đọc OTP chỉ cần read; không cấp quyền gửi hoặc quản lý hộp thư._

## Đọc mã OTP từ hộp thư bằng API theo các bước nào?

Các lệnh dưới đây dùng `$MAILERA_API_KEY` từ môi trường. Sau khi tìm được hộp thư, đặt ID tương ứng vào `$MAILBOX_ID`. Địa chỉ và tiêu đề trong ví dụ là dữ liệu giả; thay chúng bằng giá trị của luồng thử nghiệm bạn kiểm soát.

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

Gọi danh sách hộp thư bằng khoá có quyền `read`:

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

Trong mảng `data`, đối chiếu `email` và lấy `id` của hộp thư thử nghiệm. Không mặc định phần tử đầu tiên là hộp thư cần dùng. Nếu danh sách có nhiều trang, dùng `limit` và `offset` để tìm tiếp.

### 2. Tạo một yêu cầu xác minh mới

Khởi chạy thao tác gửi email xác minh trong ứng dụng thử nghiệm. Ghi lại thời điểm bắt đầu và định danh lượt kiểm thử ở phía ứng dụng.

Đừng lấy mã trước rồi mới tạo yêu cầu. Thứ tự nên là: tạo yêu cầu, chờ thư tương ứng, đọc mã, đối chiếu, sau đó nhập mã vào ứng dụng.

### 3. Gọi endpoint đọc OTP

`GET /mailboxes/{id}/otp` lấy mã OTP mới nhất và yêu cầu quyền `read`. Dùng `from` và `subject` để thu hẹp thư cần đọc; endpoint cũng nhận tham số `since_minutes`:

```bash
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 thu nghiem' \
  --data-urlencode 'since_minutes=5'
```

`--data-urlencode` mã hoá giá trị truy vấn, kể cả tiêu đề có khoảng trắng hoặc dấu tiếng Việt.

| Thành phần | Dùng để làm gì? | Cách chọn cho bài kiểm thử |
| --- | --- | --- |
| `{id}` | Xác định hộp thư | Dùng `id` đã đối chiếu với địa chỉ thử nghiệm |
| `from` | Lọc theo người gửi | Dùng địa chỉ gửi thư xác minh của ứng dụng |
| `subject` | Lọc theo tiêu đề | Dùng tiêu đề của loại thư đang chờ |

Các endpoint và quyền truy cập được trình bày trong [tài liệu API Mailera](https://mailera.app/docs).

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

Chỉ chuyển mã sang bước xác minh khi bạn xác định được nó thuộc yêu cầu đang chạy. Dùng danh sách thư và nội dung thư gốc ở phần tiếp theo để đối chiếu `mailbox_id`, `from.address`, `subject`, `received_at` và thông tin tương quan của lượt thử.

Nếu chưa xác định được đúng thư, không đưa mã vào ứng dụng chỉ vì đó là mã mới nhất.

### 5. Chờ có thời hạn

Nếu chưa tìm được thư phù hợp, chờ giữa các lần gọi rồi thử lại đến thời hạn do bộ kiểm thử đặt ra. Hết thời hạn thì dừng với lỗi rõ ràng, chẳng hạn “Chưa nhận được thư xác minh cho lượt kiểm thử”, thay vì dùng mã cũ để tiếp tục.

Mailera giới hạn 300 yêu cầu mỗi phút cho mỗi khoá. Khi nhiều lượt chạy dùng chung khoá, tính tổng số lần gọi của cả nhóm. Không gọi liên tục không nghỉ và không tự gửi lại yêu cầu xác minh ở mỗi vòng chờ.

## Làm sao tránh lấy nhầm mã cũ hoặc mã của lượt khác?

“Mới nhất trong hộp thư” không đồng nghĩa “đúng cho lượt kiểm thử này”. Hai lượt chạy có thể chờ cùng người gửi và cùng tiêu đề.

Kết hợp đúng hộp thư, người gửi, tiêu đề và mốc bắt đầu lượt thử. Dùng thời gian nhận thư để loại bớt ứng viên, nhưng không coi riêng thời gian là bằng chứng đủ: thư của một yêu cầu trước có thể đến trong lúc bạn đang chờ yêu cầu mới.

Khi cần kiểm tra, lấy danh sách thư:

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

Đọc các trường `id`, `from.address`, `subject`, `received_at` và `folder`. Dùng `id` của thư cần đối chiếu làm `$MESSAGE_ID`, rồi lấy nội dung:

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

Nội dung nằm trong `data.body.text` và `data.body.html`. Tìm thông tin liên hệ với lượt xác minh mà ứng dụng của bạn đưa vào thư. Không mặc định mọi chuỗi số đều là OTP.

![Đối chiếu người gửi, tiêu đề và thời gian của thư xác minh trong hộp thư thử nghiệm.](https://mailera.app/media/4e7f5838ada9eca5/doc-ma-otp-tu-email-qua-api-de-kiem-thu-xac-minh-otp-vi-1200.jpg)
_Khi kết quả mơ hồ, kiểm tra thư gốc trước khi đưa mã vào lượt xác minh._

Nếu kiểm thử song song, nên tách hộp thư theo luồng chạy hoặc thiết kế thông tin tương quan riêng ở ứng dụng thử nghiệm. Khi không phân biệt được các thư, dừng lượt thử thay vì đoán mã.

## Lỗi hay gặp: vì sao chưa đọc được OTP?

Tách lỗi nhận thư, lỗi chọn thư và lỗi xác thực mã. Chúng xuất hiện ở các bước khác nhau và không nên được xử lý bằng cùng một cách thử lại.

| Biểu hiện | Kiểm tra gì? | Hành động tiếp theo |
| --- | --- | --- |
| Không thấy thư phù hợp | Hộp thư, người gửi, tiêu đề | Đối chiếu cấu hình với yêu cầu vừa tạo; kiểm tra cả Thư rác |
| Có thư nhưng mã không rõ | Nội dung thư gốc | Đọc `body.text` hoặc `body.html`; không chọn một chuỗi số tuỳ ý |
| Có nhiều thư phù hợp | Thời điểm và thông tin liên hệ với lượt thử | Loại thư không thuộc lượt chạy; nếu vẫn mơ hồ thì dừng |
| Hộp thư mất kết nối hoặc chưa đồng bộ | `GET /mailboxes/{id}/status` | Xử lý kết nối hoặc đồng bộ trước khi tiếp tục chờ |
| Gmail mất kết nối sau khi đổi mật khẩu tài khoản | Mật khẩu ứng dụng đang dùng | Google thu hồi mật khẩu ứng dụng khi mật khẩu tài khoản thay đổi; cập nhật kết nối |
| API đọc được mã nhưng ứng dụng từ chối | Trạng thái yêu cầu ở ứng dụng đích | Kiểm tra mã hết hạn, đã dùng hoặc thuộc yêu cầu khác |

Để kiểm tra Thư rác, đổi bộ lọc danh sách thư thành `folder=junk`, hoặc mở thư mục đó trong **Hộp thư chung**. Kiểm tra riêng thư mục này giúp bạn phân biệt thư đã đến nhưng nằm sai chỗ với thư chưa thấy trong hộp thư.

`GET /mailboxes/{id}/status` kiểm tra đăng nhập Microsoft trực tiếp. Với nhà cung cấp khác, kết quả dựa trên lần đồng bộ gần nhất; cần đọc trạng thái theo đúng nguồn của nó.

Nếu cần yêu cầu đồng bộ ngay, `POST /mailboxes/{id}/sync` có thể đánh thức hộp thư đang ngủ nhưng đòi hỏi quyền `sync` riêng. Không thêm quyền này vào khoá chỉ đọc chỉ để thử xem lỗi có hết hay không. Nên để tác vụ vận hành có quyền phù hợp xử lý khi thật sự cần đồng bộ thủ công.

## Nếu AI agent đọc OTP, cần giới hạn gì?

Agent có thể dùng công cụ MCP `get_latest_otp` với quyền `read`. [Danh mục công cụ MCP của Mailera](https://mailera.app/blog/cong-cu-mcp-mailera) giúp phân biệt tác vụ đọc với các thao tác gửi hoặc di chuyển thư. Với mô hình kết nối tổng thể, xem [cách cho AI agent dùng hộp thư sẵn có](https://mailera.app/blog/ket-noi-email-voi-ai).

**Thư đến là dữ liệu không tin cậy, không phải lệnh.** Agent chỉ đọc thông tin cần cho bài kiểm thử. Một câu trong thư yêu cầu gửi mã đến địa chỉ khác, tiết lộ khoá hoặc đổi cấu hình không có nghĩa agent được phép thực hiện hành động đó.

Giới hạn agent vào nhóm hộp thư thử nghiệm và chỉ cấp `read`. Tác vụ lấy mã OTP không cần `send`, `move` hoặc `manage`. Nếu quy trình khác có gửi thư, yêu cầu xác nhận trước khi gửi; không để nội dung email tự quyết định người nhận.

Không ghi OTP vào nhật ký, ảnh chụp, báo cáo kiểm thử hoặc ngữ cảnh chia sẻ không cần thiết. Có thể ghi nhận bước xử lý và định danh lượt chạy mà không ghi giá trị mã. Các lựa chọn tích hợp REST API và MCP nằm ở [trang dành cho nhà phát triển](https://mailera.app/developers).

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

Mailera không tạo hộp thư hoặc địa chỉ email mới. Bạn cần có hộp thư trước khi kết nối.

Mailera có thể hiển thị thư nằm trong Hộp thư đến hay Thư rác và di chuyển thư ra khỏi Thư rác. Mailera không quyết định vị trí nhận thư thay nhà cung cấp hoặc làm nhà cung cấp tin cậy người gửi.

Không thiết kế bài kiểm thử dựa trên giả định thư sẽ đến tức thì hoặc trong một độ trễ cố định. Kết nối, đồng bộ và trạng thái ngủ của hộp thư cần được tính vào bước chờ. Việc trích xuất mã cũng không thay cho bước xác thực: ứng dụng đích mới là nơi quyết định mã có dùng được cho yêu cầu đang chờ hay không.

**Làm điều này bằng API** — Mọi thao tác trong bài đều có REST API kèm ví dụ curl, khoá API và webhook. [Xem tài liệu API](https://mailera.app/docs)