---
title: "Kết nối email với AI: đọc hộp thư hiện có qua REST API hoặc MCP"
description: "Hướng dẫn kết nối Outlook, Gmail và IMAP với AI qua Mailera: chọn xác thực, tạo khóa chỉ đọc, gọi REST API hoặc MCP và kiểm tra lỗi đồng bộ."
url: https://mailera.app/blog/ket-noi-email-voi-ai-qua-rest-api-mcp
published: 2026-10-25
updated: 2026-10-25
---

# Kết nối email với AI: đọc hộp thư hiện có qua REST API hoặc MCP

Nối Outlook, Gmail hoặc hộp thư IMAP với tác nhân AI mà không đổi địa chỉ email. Bắt đầu bằng quyền chỉ đọc, kiểm tra đúng thư thử rồi mới mở rộng tác vụ.

## Bạn cần kết nối hộp thư hay dịch vụ gửi email?

Nếu tác nhân cần đọc thư khách hàng gửi đến địa chỉ đang dùng, bạn cần kết nối hộp thư đó. Đây là việc khác với gửi thư giao dịch từ ứng dụng: đầu vào là thư đã nằm trong tài khoản Outlook, Gmail hoặc máy chủ thư của bạn.

[Mailera kết nối hộp thư hiện có](https://mailera.app/product) với ứng dụng và AI agent qua REST API, MCP và webhook. Bạn xác thực với nhà cung cấp để nối hộp thư vào Mailera, rồi cấp cho tác nhân một khóa API có phạm vi riêng. Không đưa mật khẩu hộp thư trực tiếp vào lời nhắc của tác nhân. Bài [dùng hộp thư hiện có cho AI agent](https://mailera.app/blog/ket-noi-email-voi-ai) giải thích thêm về mô hình này.

Nên bắt đầu bằng một thử nghiệm nhỏ: dùng hộp thư thử do bạn quản lý, tự gửi một thư có tiêu đề dễ nhận ra, rồi yêu cầu tác nhân đọc và tóm tắt thư đó. Chưa cần cho phép gửi, di chuyển thư hoặc quản lý hộp thư.

![Luồng kết nối hộp thư hiện có với tác nhân AI qua Mailera, REST API hoặc MCP](https://mailera.app/media/425ed5a8a10c39d0/ket-noi-email-voi-ai-doc-hop-thu-hien-co-qua-rest-api-hoac-vi-1200.jpg)
_Xác thực hộp thư và cấp quyền cho tác nhân là hai bước riêng._

## Cách xác thực theo từng nhà cung cấp

Chọn cách xác thực theo nhà cung cấp, không dùng cùng một loại mật khẩu cho mọi hộp thư. Bảng dưới là các nhánh kết nối trong Mailera; [danh sách nhà cung cấp](https://mailera.app/providers) có trang riêng cho từng dịch vụ.

| Hộp thư | Cách kết nối trong Mailera | Điều cần chuẩn bị |
| --- | --- | --- |
| [Outlook, Hotmail, Microsoft 365](https://mailera.app/providers/microsoft) | OAuth qua Microsoft Graph | Đăng nhập Microsoft và hoàn thành bước cấp quyền; không dùng mật khẩu ứng dụng |
| [Gmail, Google Workspace](https://mailera.app/providers/gmail) | Mật khẩu ứng dụng qua IMAP/SMTP | Bật xác minh 2 bước; tài khoản và chính sách quản trị phải cho phép tạo mật khẩu ứng dụng |
| [Yahoo Mail](https://mailera.app/providers/yahoo) | Mật khẩu ứng dụng | Thông tin kết nối dành cho ứng dụng của tài khoản |
| [iCloud Mail](https://mailera.app/providers/icloud) | Mật khẩu dành riêng cho ứng dụng | Apple Account đã bật xác thực hai yếu tố |
| [Zoho Mail](https://mailera.app/providers/zoho) | Mật khẩu ứng dụng | Bật IMAP và kiểm tra tài khoản có quyền truy cập IMAP |
| Fastmail, AOL, Yandex, Mail.ru, Naver | Nhánh mật khẩu ứng dụng | Xem điều kiện của nhà cung cấp được chọn trong biểu mẫu |
| [Daum](https://mailera.app/providers/daum) | Nhánh mật khẩu ứng dụng, chỉ nhận thư | Mailera giới hạn Daum ở chế độ chỉ nhận do giới hạn cổng SMTP |
| [Máy chủ riêng qua IMAP/SMTP](https://mailera.app/providers/imap) | Cấu hình tùy chỉnh | Máy chủ IMAP, thông tin đăng nhập; SMTP nếu cần gửi |

Khi kết nối Outlook với AI, dùng nhánh **Đăng nhập Microsoft**. [Tài liệu Outlook mail của Microsoft Graph](https://learn.microsoft.com/en-us/graph/api/resources/mail-api-overview?view=graph-rest-1.0) mô tả quyền truy cập được cấp phép vào thư của tài khoản cá nhân và tổ chức. Đây là nhánh Mailera dùng cho Microsoft, không phải IMAP với mật khẩu ứng dụng. Xem các bước riêng trong bài [kết nối Outlook bằng OAuth qua Microsoft Graph](https://mailera.app/blog/ket-noi-outlook-bang-oauth).

Khi kết nối Gmail với AI qua Mailera, luồng hiện tại dùng mật khẩu ứng dụng (app password) qua IMAP/SMTP. Theo [hướng dẫn mật khẩu ứng dụng của Google](https://support.google.com/accounts/answer/185833), tài khoản phải bật xác minh 2 bước. Google khuyến nghị ưu tiên “Sign in with Google” khi ứng dụng hỗ trợ; luồng Gmail hiện tại của Mailera dùng mật khẩu ứng dụng. Tùy chọn mật khẩu ứng dụng có thể không xuất hiện với tài khoản tổ chức, tài khoản chỉ dùng khóa bảo mật cho xác minh 2 bước hoặc tài khoản bật Advanced Protection. Nếu không thấy tùy chọn, kiểm tra điều kiện tài khoản thay vì nhập mật khẩu đăng nhập thông thường.

[Apple yêu cầu xác thực hai yếu tố](https://support.apple.com/en-us/102654) để tạo và dùng mật khẩu dành riêng cho ứng dụng. Với Zoho, [hướng dẫn IMAP chính thức](https://www.zoho.com/mail/help/imap-access.html) yêu cầu bật IMAP, dùng mật khẩu ứng dụng khi bật xác thực hai yếu tố, đồng thời nêu rằng tài khoản gói miễn phí đăng ký mới không có IMAP. Thông số máy chủ Zoho cần lấy trong tài khoản vì phụ thuộc loại tài khoản và trung tâm dữ liệu.

## Kết nối và kiểm tra hộp thư đầu tiên

### 1. Chuẩn bị hộp thư và quyền thêm

Dùng hộp thư thuộc quyền quản lý của bạn. Trong Mailera, chỉ vai trò Admin hoặc Leader được thêm hộp thư. Nên đặt hộp thư thử vào một nhóm riêng để sau đó giới hạn khóa của tác nhân vào đúng nhóm này.

### 2. Chọn nhánh kết nối

Mở **Danh sách hộp thư → Thêm hộp thư**. Với Microsoft, chọn **Đăng nhập Microsoft** và hoàn thành xác thực tại Microsoft.

Với nhà cung cấp khác, chọn **Một hộp thư**, nhập **Địa chỉ email**, rồi kiểm tra nhà cung cấp được nhận diện. Nếu cần, chọn lại trong **Hoặc chọn nhà cung cấp** và nhấn **Tiếp tục**. Với máy chủ riêng, chọn **IMAP tùy chỉnh**.

![Màn hình Thêm hộp thư trong Mailera với nhánh Microsoft, Gmail và IMAP tùy chỉnh](https://mailera.app/media/39e644d283f9e836/ket-noi-email-voi-ai-doc-hop-thu-hien-co-qua-rest-api-hoac-vi-1200.jpg)
_Kiểm tra nhà cung cấp được nhận diện trước khi nhập thông tin kết nối._

### 3. Nhập thông tin xác thực

Ở nhánh mật khẩu ứng dụng, đọc **Cách lấy mật khẩu ứng dụng** và **Cần chuẩn bị**. Trong **Thông tin kết nối**, trường **Mật khẩu** nhận mật khẩu ứng dụng, không phải mật khẩu đăng nhập thông thường. Chọn **Nhóm quản lý** phù hợp với phạm vi dự định cấp cho tác nhân.

Với máy chủ riêng, điền **Máy chủ nhận thư (IMAP)**, **Cổng** và **Bảo mật** theo cấu hình thực tế. Phần **Máy chủ gửi thư (SMTP)** là tùy chọn. **Tự dò cấu hình** có thể điền cấu hình công khai của tên miền khi có; hãy đối chiếu lại với quản trị viên máy chủ.

### 4. Kiểm tra nhận và gửi riêng

Nhấn **Kiểm tra & kết nối**. Mailera đăng nhập thử và nhận diện thư mục; thao tác này không gửi email.

Nếu thấy **Nhận thư được, gửi thư chưa được**, bạn có thể chọn **Lưu ở chế độ Chỉ nhận** khi mục tiêu chỉ là đọc thư. Nếu cần gửi về sau, chọn **Sửa thông tin** rồi **Kiểm tra lại**. Không coi IMAP thành công là SMTP cũng thành công: [chuẩn IMAP](https://www.rfc-editor.org/rfc/rfc9051.html) tách việc truy cập thư khỏi việc gửi thư.

### 5. Đối chiếu một thư thử

Kết nối thành công chưa có nghĩa là đã tải xong thư. Mailera tải thư lần đầu trong thời hạn lưu trữ, ưu tiên thư mới nhất. Theo dõi thông báo **Đang tải thư lần đầu…** và **Đã tải xong thư lần đầu**.

Tự gửi thư thử từ giao diện nhà cung cấp đến hộp thư vừa nối. Mở **Hộp thư chung**, chọn đúng hộp thư và đối chiếu tiêu đề, người gửi, nội dung. Đây sẽ là thư bạn dùng để kiểm tra REST API hoặc MCP, tránh đọc nhầm một thư khác rồi kết luận tác nhân đã hoạt động đúng.

## Cho tác nhân đọc qua REST API hay MCP?

REST API phù hợp khi bạn tự viết ứng dụng và muốn kiểm soát từng lần gọi. MCP là giao thức kết nối ứng dụng dùng mô hình ngôn ngữ với nguồn dữ liệu và công cụ bên ngoài; chọn MCP khi trình khách của tác nhân đã hỗ trợ giao thức này.

| Nhu cầu | Cách dùng |
| --- | --- |
| Tự viết luồng đọc thư, chọn lúc gọi và xử lý kết quả | REST API |
| Cho tác nhân trong Claude, Cursor hoặc VS Code dùng công cụ đọc thư | MCP |
| Nhận thông báo sự kiện để ứng dụng xử lý tiếp | Webhook |

### Tạo khóa chỉ có quyền đọc

Trong **Cài đặt**, mở tab **API key** rồi chọn **Tạo key**. Điền **Tên gợi nhớ**, đặt **Phạm vi hộp thư** vào nhóm thử và chỉ cấp quyền `read`. Không bật `send`, `move` hoặc `manage` để thử đọc thư.

Đặt **Thời hạn** phù hợp với đợt thử; dùng **Giới hạn IP (tuỳ chọn)** nếu môi trường chạy có IP xác định. Admin có thể chọn tất cả nhóm, nhưng nếu tác nhân chỉ cần đọc nhóm thử, không nên cấp phạm vi rộng hơn mức cần thiết.

Khóa chỉ xuất hiện một lần tại **Key đã tạo — sao chép ngay**. Lưu khóa vào nơi quản lý bí mật của ứng dụng. Không dán khóa vào hội thoại để nhờ tác nhân tự cấu hình.

![Tạo khóa API chỉ đọc và giới hạn vào một nhóm hộp thư thử trong Mailera](https://mailera.app/media/cfb880473bb88542/ket-noi-email-voi-ai-doc-hop-thu-hien-co-qua-rest-api-hoac-vi-1200.jpg)
_Chỉ cấp quyền đọc cho lần thử đầu tiên; không chọn tất cả nhóm nếu không cần._

### Luồng REST: hộp thư → danh sách thư → nội dung

Các lệnh dưới dùng biến môi trường `$MAILERA_API_KEY`. Sau mỗi bước, lấy ID từ phản hồi và đặt vào `$MAILBOX_ID` hoặc `$MESSAGE_ID` tương ứng trong môi trường chạy.

**Liệt kê hộp thư được phép đọc:**

```bash
curl --fail-with-body \
  'https://mailera.app/api/public/v1/mailboxes?limit=1' \
  -H "Authorization: Bearer $MAILERA_API_KEY"
```

Đối chiếu `data[].email` với hộp thư thử rồi lấy `data[].id` làm `$MAILBOX_ID`. `limit=1` chỉ lấy một hộp thư; nếu nhóm có nhiều hộp thư, dùng các tham số `q`, `limit` hoặc `offset` theo [tài liệu API Mailera](https://mailera.app/docs) để tìm đúng hộp.

**Liệt kê thư trong Hộp thư đến:**

```bash
curl --fail-with-body \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=10" \
  -H "Authorization: Bearer $MAILERA_API_KEY"
```

Tìm thư thử qua `subject`, `from` và `received_at`, rồi lấy `id` của thư làm `$MESSAGE_ID`. Nếu chưa thấy, kiểm tra đúng thư mục trước; ví dụ này đang lọc theo `folder=inbox`. Đổi giá trị `folder` nếu thư thử nằm ở thư mục khác. Khi cần đọc tiếp danh sách, dùng `next_cursor` làm tham số `cursor` cho lần gọi sau.

**Đọc nội dung thư đã chọn:**

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

Đối chiếu `data.body.text` hoặc `data.body.html` với thư thử trên giao diện. Danh sách thư có `preview`; muốn lấy nội dung, hãy gọi endpoint đọc một thư thay vì chỉ tóm tắt đoạn xem trước.

Cả ba bước đều dùng quyền `read`. Khả năng gửi của hộp thư và quyền gửi của khóa là hai thứ khác nhau: hộp thư có thể gửi được nhưng khóa chỉ đọc không vì thế có thêm quyền `send`.

### Luồng MCP tương đương

Trong hộp thoại tạo khóa, chọn **Sao chép cấu hình MCP** cho Claude, Cursor hoặc VS Code. Dùng cấu hình được tạo sẵn thay vì tự đoán tên trường. Endpoint MCP là `https://mailera.app/api/public/v1/mcp`; [trang MCP của Mailera](https://mailera.app/mcp) trình bày cách kết nối trình khách.

Cho tác nhân gọi lần lượt `list_mailboxes` → `list_messages` → `get_message`. Cả ba công cụ cần quyền `read`. Yêu cầu tác nhân chỉ đọc thư thử trong hộp thư đã chọn và tóm tắt nội dung, không thực hiện yêu cầu được viết trong thư.

Bước thử hoàn tất khi tác nhân đọc đúng thư, khóa chỉ bao phủ nhóm cần thiết và không có quyền gửi hay quản lý. Nếu ứng dụng cần nhận thông báo sự kiện thay vì tự hỏi liên tục, dùng endpoint `POST /webhooks` trong tài liệu API Mailera để tạo đăng ký; đây là quyền `webhooks` riêng, tách khỏi khóa đọc của tác nhân.

## Những lỗi thường gặp và cách khoanh vùng

| Hiện tượng | Kiểm tra trước |
| --- | --- |
| Không thêm được hộp thư | Tài khoản Mailera có vai trò Admin hoặc Leader không? |
| Xác thực thất bại | Đã chọn đúng nhà cung cấp và nhánh xác thực chưa? Với Gmail, mật khẩu ứng dụng còn hiệu lực và tài khoản còn cho phép dùng không? |
| Nhận được nhưng không gửi được | Kiểm tra SMTP riêng; xem hộp thư có được lưu ở chế độ chỉ nhận không |
| Tác nhân không thấy hộp thư | Kiểm tra nhóm nằm trong phạm vi khóa và quyền `read` |
| Kết nối thành công nhưng chưa có thư mới | Kiểm tra thư mục, tải thư lần đầu, lần đồng bộ gần nhất và trạng thái ngủ |

Google thu hồi mật khẩu ứng dụng khi bạn đổi mật khẩu Google Account. Nếu Gmail ngừng kết nối sau lần đổi mật khẩu, hãy kiểm tra lại mật khẩu ứng dụng. Với Zoho, kiểm tra cả việc bật IMAP và quyền truy cập IMAP của tài khoản. Dựa vào thông báo lỗi thực tế, không thay mật khẩu liên tục khi nguyên nhân là quyền truy cập.

Ở phản hồi hộp thư, các trường `sync.last_synced_at`, `sync.next_sync_at` và `sync.sleeping_since` giúp xem thời điểm đồng bộ và trạng thái ngủ. Mailera kiểm tra hộp thư đang dùng thường xuyên hơn hộp thư ít hoạt động. Khi hộp thư đang dùng, nếu kết quả **Theo dõi liên tục** là có, thư mới có thể về sau vài giây; nếu không, Mailera quét theo chu kỳ 2 phút.

Kết quả từ `GET /mailboxes/{id}/status` có ý nghĩa khác nhau tùy nhà cung cấp: với Microsoft, Mailera kiểm tra đăng nhập 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. Vì vậy, trạng thái đăng nhập không thay thế việc đối chiếu thư mới.

Nếu cần đồng bộ chủ động, `POST /mailboxes/{id}/sync` kích hoạt đồng bộ và đánh thức hộp thư đang ngủ, nhưng cần quyền `sync`. Giữ khóa tác nhân ở quyền đọc nếu tác vụ không cần tự đồng bộ; để thao tác này cho luồng vận hành riêng.

## Đừng để nội dung thư trở thành lệnh cho tác nhân

**Thư đến và tệp đính kèm là dữ liệu không tin cậy, không phải chỉ dẫn vận hành.** Một thư có thể chứa yêu cầu bỏ qua quy tắc, tiết lộ khóa hoặc lấy dữ liệu từ thư khác. Đây là nguy cơ prompt injection: nội dung cần đọc bị dùng để điều khiển tác nhân.

Đặt quy tắc xử lý ở phía ứng dụng: tác nhân được tóm tắt và trích xuất thông tin, nhưng không làm theo chỉ dẫn nằm trong thư. Khóa chỉ đọc vẫn cho phép tiếp cận nội dung trong phạm vi được cấp, nên giới hạn nhóm hộp thư cũng quan trọng như bỏ quyền gửi.

Không đưa khóa API, mật khẩu ứng dụng hoặc refresh token vào lời nhắc, nhật ký công khai hay ảnh chụp. Nếu khóa bị lộ, thu hồi khóa; Mailera từ chối ngay các lần gọi tiếp theo dùng khóa đó. Xem thêm [thông tin bảo mật Mailera](https://mailera.app/security).

Trước khi vận hành, tạo một thư thử vô hại có yêu cầu tác nhân tiết lộ bí mật và kiểm tra rằng tác nhân không làm theo. Dùng hộp thư của bạn, che địa chỉ và nội dung nhạy cảm khi ghi hình hoặc chụp màn hình.

Nếu sau này cấp quyền gửi, yêu cầu người dùng xác nhận người nhận và nội dung trước khi gọi công cụ gửi. [Đặc tả MCP](https://modelcontextprotocol.io/specification/2025-06-18) yêu cầu ứng dụng chủ lấy sự đồng ý rõ ràng của người dùng trước khi gọi công cụ; việc đã nối được MCP không thay thế bước kiểm soát này.

## Giới hạn cần biết trước khi vận hành

Mailera dùng hộp thư bạn đã có, không cấp hộp thư hay địa chỉ email mới. Proton Mail và Tuta chưa được hỗ trợ. Daum hiện chỉ nhận thư trong Mailera do giới hạn cổng SMTP trong cấu hình nhà cung cấp của Mailera.

Mailera không bảo đảm cập nhật theo thời gian thực cho mọi hộp thư. Hộp thư ít hoạt động có thể được kiểm tra thưa hơn hoặc chuyển sang trạng thái ngủ. Hãy kiểm tra trạng thái đồng bộ khi quy trình của bạn phụ thuộc vào một thư vừa đến.

Mailera không cung cấp gửi email tiếp thị hàng loạt.

**Kết nối hộp thư đầu tiên trong 2 phút** — Thêm hộp thư Outlook, Gmail hoặc IMAP và đọc thư qua giao diện hoặc API. [Kết nối hộp thư](https://mailera.app/auth?mode=signup)