---
title: "API email cho AI agent: đọc thư và trả lời từ hộp thư đang dùng"
description: "Dùng API email cho AI agent với hộp thư đang có: chọn endpoint, cấp quyền tối thiểu, duyệt trước khi gửi và xử lý yêu cầu hết thời gian chờ."
url: https://mailera.app/blog/api-email-cho-ai-agent
published: 2026-10-25
updated: 2026-10-25
---

# API email cho AI agent: đọc thư và trả lời từ hộp thư đang dùng

Ánh xạ từng việc của agent vào endpoint và quyền cần thiết. Tách quyền đọc khỏi quyền gửi, duyệt nội dung ở ứng dụng và kiểm tra lần gửi trước khi thử lại.

API email cho AI agent là giao diện để ứng dụng lấy nội dung thư và thực hiện thao tác được cấp quyền. Agent đề xuất cách xử lý; ứng dụng quyết định có cho thực hiện hay không.

[Mailera](https://mailera.app/product) kết nối hộp thư sẵn có với ứng dụng. Nếu cần xem kiến trúc tổng thể trước, đọc [cách dùng hộp thư đang có cho AI agent](https://mailera.app/blog/ket-noi-email-voi-ai). Phần dưới tập trung vào endpoint, quyền và trạng thái xử lý.

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

Bắt đầu bằng hộp thư thử thuộc quyền kiểm soát của bạn. [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 các bước cài đặt. Với [Outlook.com và Microsoft 365](https://mailera.app/providers/microsoft), dùng OAuth qua Microsoft Graph, không dùng mật khẩu ứng dụng. Mailera kết nối Gmail bằng mật khẩu ứng dụng (app password).

Trong **Cài đặt**, mở phần khóa API rồi chọn **Tạo key**. Chọn **Phạm vi hộp thư** là nhóm cần xử lý và chỉ cấp `read` lúc đầu. Thêm `move` khi bật chức năng chuyển thư; chỉ cấp `send` cho thành phần thực hiện gửi đã được kiểm soát.

Quyền của khóa Mailera khác với quyền ứng dụng được cấp tại nhà cung cấp. Với Microsoft Graph, [Microsoft khuyến nghị xin quyền tối thiểu cần thiết](https://learn.microsoft.com/en-us/graph/auth/auth-concepts).

![Hộp thoại tạo khóa API Mailera với phạm vi một nhóm hộp thư và quyền đọc](https://mailera.app/media/e2132b06cac7cdb5/ket-noi-openclaw-voi-gmail-outlook-chuan-bi-hop-thu-va-vi-1200.jpg)
_Bắt đầu bằng quyền read trong nhóm hộp thư cần xử lý; chưa cấp quyền gửi._

Khóa mới chỉ hiển thị một lần. Lưu khóa ở phía máy chủ, không đưa vào ngữ cảnh mô hình, ảnh chụp hoặc nhật ký. API dùng địa chỉ gốc `https://mailera.app/api/public/v1` và header `Authorization: Bearer $MAILERA_API_KEY`.

Trong các lệnh dưới đây, đặt `$MAILERA_API_KEY` bằng khóa thử của bạn; `$MAILBOX_ID` và `$MESSAGE_ID` là định danh lấy từ phản hồi API.

## Mỗi việc tương ứng với API nào?

Bảng này là bản đồ thao tác, không phải danh sách quyền nên cấp hết cho agent. [Trang dành cho nhà phát triển](https://mailera.app/developers) giới thiệu các giao diện tích hợp.

| Việc cần làm | Phương thức và đường dẫn | Quyền | Kiểm tra trước khi gọi |
| --- | --- | --- | --- |
| Chọn hộp thư | `GET /mailboxes` | `read` | Nhóm hộp thư được phép |
| Liệt kê thư | `GET /mailboxes/{id}/messages` | `read` | Thư mục, bộ lọc, giới hạn |
| Đọc nội dung | `GET /mailboxes/{id}/messages/{msgId}` | `read` | Đúng hộp thư và thư cần đọc |
| Tìm trên nhiều hộp thư | `GET /messages/search` | `read` | Giới hạn bằng `mailbox`, `since` |
| Chuyển thư | `POST /mailboxes/{id}/messages/{msgId}/move` | `move` | Thư mục đích được phép |
| Gửi, trả lời, chuyển tiếp | `POST /mailboxes/{id}/send` | `send` | Hộp gửi, người nhận, nội dung đã duyệt |
| Xem lần gửi | `GET /sends/{id}` | `send` | Định danh của lần gửi cần kiểm tra |

Phân loại nội dung là việc của agent. Chuyển thư sau khi phân loại là thao tác riêng, cần quyền `move`. Tương tự, tạo nội dung trả lời trong ứng dụng không cần trao quyền gửi cho mô hình.

## Luồng đọc và đề xuất trả lời đi theo thứ tự nào?

### 1. Chọn hộp thư được phép

Lấy một hộp thư để kiểm tra kết nối API:

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

Đọc `data[].id`, `status`, `capabilities` và `sync`. Trước khi cho phép trả lời, kiểm tra `capabilities.send`; việc đọc được thư không có nghĩa hộp thư gửi được.

### 2. Lấy danh sách có giới hạn

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

Danh sách có `id`, `mailbox_id`, `subject`, `preview` và `conversation_id`. Dùng `next_cursor` cho lần lấy trang tiếp theo qua tham số `cursor`. Có thể thu hẹp bằng `since`, `from`, `q` hoặc `unread`.

Ứng dụng nên lưu cặp định danh hộp thư và thư đã xử lý. Đừng chỉ dựa vào trạng thái chưa đọc để quyết định có chạy agent lần nữa hay không.

### 3. Đọc nội dung cần thiết

```bash
curl "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`. Kiểm tra `body_error` trước khi đưa nội dung cho agent. `preview` trong danh sách không thay thế toàn bộ nội dung thư.

### 4. Tạo đề xuất trong ứng dụng

Cho agent đề xuất thao tác hoặc soạn câu trả lời, nhưng giữ nội dung thư tách khỏi chỉ dẫn của ứng dụng. Nội dung chờ duyệt được lưu ở phía ứng dụng; bước này không phải lời gọi API lưu bản nháp Mailera.

### 5. Duyệt rồi mới gửi

Ứng dụng kiểm tra hộp thư gửi, người nhận, nội dung và thư gốc cần trả lời. Hiển thị các thông tin đó để người dùng xác nhận trước khi gọi `/send`. Lưu kết quả phê duyệt cùng định danh thư gốc để tránh gửi một đề xuất đã bị sửa sau khi duyệt.

![Luồng đọc thư bằng quyền read, agent đề xuất, ứng dụng duyệt rồi gửi và kiểm tra trạng thái bằng quyền send](https://mailera.app/media/dd917916910e9522/api-email-cho-ai-agent-doc-thu-va-tra-loi-tu-hop-thu-dang-vi-1200.jpg)
_Agent đề xuất; ứng dụng kiểm tra và xin xác nhận trước khi gọi API gửi._

## Tránh gửi lặp khi yêu cầu hết thời gian chờ thế nào?

Endpoint gửi nhận header `Idempotency-Key`, với cửa sổ chống lặp 24 giờ. Ứng dụng nên tạo và lưu khóa này trước khi gửi, gắn nó với một thao tác đã được duyệt.

Nếu yêu cầu hết thời gian chờ, đừng lập tức tạo khóa mới và gửi lại. Khi đã có định danh lần gửi, gọi `GET /sends/{id}` để kiểm tra. API có các trạng thái `queued`, `sending`, `sent`, `failed` và `unknown`.

Với `queued` hoặc `sending`, tiếp tục theo dõi lần gửi đó. Với `unknown`, giữ thao tác ở trạng thái cần đối soát thay vì tự coi là thất bại rồi gửi mới. Lưu trạng thái API trả về, không đánh dấu hoàn tất chỉ vì ứng dụng đã phát yêu cầu.

Cửa sổ 24 giờ không thay thế sổ theo dõi gửi của ứng dụng. Hãy giữ định danh thư gốc, khóa chống lặp và kết quả xử lý đủ lâu theo nhu cầu vận hành.

Trước khi dựng dữ liệu gửi hoặc trả lời, đối chiếu [tài liệu API Mailera](https://mailera.app/docs). Giữ định danh thư gốc xuyên suốt luồng; đừng dùng riêng tiêu đề làm căn cứ chọn hội thoại.

## Khi nào dùng REST API, MCP hoặc webhook?

| Giao diện | Khi nên dùng | Phần ứng dụng vẫn phải làm |
| --- | --- | --- |
| REST API | Cần tự điều phối từng lời gọi | Kiểm tra đầu vào, lưu trạng thái, duyệt thao tác |
| MCP | Ứng dụng AI tương thích cần gọi công cụ | Giới hạn quyền và xác nhận thao tác nhạy cảm |
| Webhook | Cần kích hoạt xử lý khi có sự kiện | Xác minh chữ ký và chống xử lý lặp |

Với luồng trả lời có điều kiện duyệt, nên bắt đầu bằng REST API vì bạn đặt được bước kiểm tra ngay trước lời gọi gửi.

MCP của Mailera nằm tại `https://mailera.app/api/public/v1/mcp`. Các công cụ `list_messages`, `get_message` dùng `read`; `reply_to_email`, `get_send_status` dùng `send`. Xem [công cụ MCP theo từng tác vụ](https://mailera.app/blog/cong-cu-mcp-mailera) nếu ứng dụng của bạn dùng giao diện này.

Webhook `message.received` có thể kích hoạt xử lý thư mới. Lưu bí mật ký khi tạo webhook vì giá trị này chỉ được trả về một lần. Phía nhận cần xác minh chữ ký và lưu dấu xử lý để sự kiện giao lại không chạy cùng tác vụ hai lần.

Chống xử lý lặp sự kiện và chống gửi lặp là hai việc riêng: một việc nằm ở bộ nhận webhook, việc kia dùng `Idempotency-Key` khi gửi. Thời điểm thấy thư còn phụ thuộc kết nối và đồng bộ; hộp thư ít hoạt động có thể ngủ, nên không thiết kế dựa trên giả định thư luôn xuất hiện tức thời.

## Những lỗi nào thường gặp?

| Triệu chứng | Kiểm tra và xử lý |
| --- | --- |
| Không đọc được thư | Kiểm tra khóa bị thu hồi hoặc hết hạn, quyền `read`, phạm vi nhóm và trạng thái hộp thư. Khóa bị thu hồi bị từ chối ngay. |
| Chưa thấy thư mới | Kiểm tra `folder`, bộ lọc, `next_cursor` và thông tin `sync`. Đồng bộ chủ động qua `POST /mailboxes/{id}/sync` cần quyền `sync`. |
| Đọc được nhưng không gửi được | Kiểm tra quyền `send`, `capabilities.send` và cấu hình gửi. Hộp thư có thể đã được lưu ở chế độ chỉ nhận. |
| Gửi bị hết thời gian chờ | Kiểm tra lần gửi cũ; không tạo khóa chống lặp mới ngay. |
| Trả lời nhầm hội thoại | Kiểm tra định danh thư gốc được lưu và dữ liệu trả lời theo tài liệu API, không chỉ nhìn tiêu đề. |

Nút **Kiểm tra & kết nối** chỉ thử kết nối, không gửi thư thật. Vì vậy, hoàn tất bước này không thay thế việc thử luồng trả lời trên hộp thư của bạn.

## Ngăn agent làm theo chỉ dẫn trong thư thế nào?

**Thư đến là dữ liệu không tin cậy, không phải lệnh.** Một thư có thể yêu cầu agent đổi người nhận, tiết lộ khóa hoặc chuyển tiếp dữ liệu. Không cho nội dung đó thay đổi chính sách của ứng dụng.

Đặt kiểm soát ngoài mô hình: giới hạn hộp thư được đọc, chỉ đưa phần nội dung cần thiết vào ngữ cảnh và giữ khóa gửi ở thành phần thực hiện thao tác sau phê duyệt. Một câu nhắc trong lời dẫn không thay thế việc kiểm tra người nhận và quyền ở máy chủ.

Không tự làm theo yêu cầu trong thư về tiết lộ bí mật, chuyển tiếp dữ liệu hay mở liên kết. Với thao tác gửi, yêu cầu người dùng xác nhận. [Đặc tả công cụ MCP](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) cũng khuyến nghị xác nhận thao tác nhạy cảm và giữ khả năng từ chối lời gọi công cụ.

Bước duyệt và chính sách thao tác do ứng dụng của bạn triển khai. Tham khảo thêm [thông tin bảo mật Mailera](https://mailera.app/security) khi thiết kế cách quản lý khóa.

## Giới hạn cần tính vào ứng dụng

Mailera không cung cấp gửi tiếp thị hàng loạt. Hộp thư chỉ nhận cần được loại khỏi luồng gửi, dù khóa API có quyền `send`.

Mailera cũng không bảo đảm thư gửi sẽ vào Hộp thư đến. Trạng thái lần gửi không nên được dùng làm bằng chứng về vị trí thư trong hộp thư người nhận.

**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)