---
title: "Gmail API và IMAP: chọn cách đọc Gmail cho AI agent"
description: "So sánh Gmail API và IMAP cho AI agent: quyền OAuth, nhãn, đồng bộ và công sức triển khai. Hướng dẫn đọc Gmail qua Mailera bằng khóa chỉ có quyền read."
url: https://mailera.app/blog/gmail-api-va-imap-cho-ai-agent
published: 2026-10-25
updated: 2026-10-25
---

# Gmail API và IMAP: chọn cách đọc Gmail cho AI agent

Chọn theo quyền đọc, cách đồng bộ và phần kết nối bạn muốn tự vận hành. Mailera dùng IMAP với mật khẩu ứng dụng để kết nối Gmail, rồi cung cấp REST API và MCP cho agent.

## Nên chọn Gmail API hay IMAP cho tác nhân AI?

Nếu agent chỉ cần đọc Gmail, điểm nên xét trước là quyền truy cập. Gmail API có phạm vi `gmail.readonly`; Gmail IMAP cũng hỗ trợ OAuth, nhưng phạm vi OAuth tiêu chuẩn cho IMAP là `https://mail.google.com/`, rộng hơn nhu cầu chỉ đọc.

Gmail API là giao diện lập trình dành riêng cho Gmail. IMAP là giao thức truy cập thư, có thể dùng với nhiều nhà cung cấp. IMAP không phải giao thức gửi thư; kết nối Gmail của Mailera dùng SMTP cho phần gửi.

Nếu bạn cần một giao diện chung cho các hộp thư đang có, [Mailera cung cấp REST API, MCP và webhook](https://mailera.app/product). Đây là một lớp truy cập khác, không phải cách gọi Gmail API gián tiếp.

![Hai đường đọc Gmail: agent tự dùng Gmail API hoặc đi qua REST API và MCP của Mailera tới IMAP.](https://mailera.app/media/070a5a1cf3d9fc9c/gmail-api-va-imap-chon-cach-doc-gmail-cho-ai-agent-access-vi-1200.jpg)
_IMAP cũng hỗ trợ OAuth; mật khẩu ứng dụng là cách kết nối Gmail hiện có của Mailera._

## Gmail API và IMAP khác nhau ở những điểm nào?

| Tiêu chí | Gmail API | Gmail IMAP | Tác động đến agent |
| --- | --- | --- | --- |
| Nhãn và chuỗi thư | Làm việc qua API riêng của Gmail | Gmail biểu diễn nhãn như thư mục; có phần mở rộng cho nhãn và chuỗi thư | Không coi mọi thư mục là một tập thư độc lập |
| Lấy nội dung | Đồng bộ đầy đủ dùng `messages.list`, rồi `messages.get` | Có lệnh `FETCH`; `X-GM-RAW` hỗ trợ cú pháp tìm kiếm Gmail | Tách bước tìm thư khỏi bước đọc nội dung |
| Đồng bộ thay đổi | Dùng `history.list` với `startHistoryId` | Cần xử lý đồng bộ theo giao thức và thư viện IMAP đã chọn | Phải có cách phục hồi khi trạng thái đồng bộ không còn dùng được |
| Thông báo thay đổi | Qua Cloud Pub/Sub; thông báo chứa địa chỉ email và history ID | Là đường kết nối riêng, không phải cơ chế Pub/Sub của Gmail API | Nhận thông báo chưa đồng nghĩa với đã có nội dung thư |
| Quyền truy cập | Có `gmail.readonly`, `gmail.metadata`, `gmail.send` | Hỗ trợ OAuth; phạm vi tiêu chuẩn là `https://mail.google.com/` | Gmail API phù hợp hơn khi cần quyền Google chi tiết |
| Nhiều nhà cung cấp | Dành cho Gmail | Dùng được với các nhà cung cấp hỗ trợ IMAP | IMAP giúp dùng chung giao thức, nhưng vẫn có đặc thù từng nơi |
| Vận hành | Quản lý OAuth, lịch sử đồng bộ, theo dõi thay đổi và quota | Quản lý xác thực, kết nối và ánh xạ thư mục | Chọn phần việc đội của bạn có thể duy trì |

Theo [tài liệu OAuth cho Gmail IMAP](https://developers.google.com/workspace/gmail/imap/xoauth2-protocol), Google khuyên chuyển sang Gmail API nếu ứng dụng không cần phạm vi đầy đủ. Vì vậy, “IMAP hay API” và “OAuth hay mật khẩu ứng dụng” là hai quyết định khác nhau.

IMAP cũng không làm mất hoàn toàn thông tin riêng của Gmail. Các [phần mở rộng Gmail IMAP](https://developers.google.com/workspace/gmail/imap/imap-extensions) gồm `X-GM-LABELS` cho nhãn, `X-GM-MSGID` để nhận diện cùng một thư qua nhiều thư mục và `X-GM-THRID` cho mã chuỗi thư. Khi chọn thư viện, hãy kiểm tra những phần này nếu agent cần gom hội thoại hoặc tránh đọc trùng.

Về đồng bộ, [hướng dẫn push của Google](https://developers.google.com/workspace/gmail/api/guides/push) yêu cầu gia hạn `watch` ít nhất mỗi 7 ngày. Thông báo có thể chậm hoặc bị mất; ứng dụng vẫn cần lấy thay đổi và nội dung sau đó.

## Khi nào nên tự tích hợp, khi nào nên dùng Mailera?

**Chọn Gmail API** nếu chỉ dùng Gmail và cần giới hạn quyền ngay tại Google. Theo [danh sách phạm vi Gmail API](https://developers.google.com/workspace/gmail/api/auth/scopes), `gmail.readonly` cho phép xem thư và cài đặt; `gmail.metadata` chỉ cho đọc siêu dữ liệu như nhãn, tiêu đề, không có thân thư. Quyền gửi nằm ở `gmail.send` riêng.

Cần tính cả việc triển khai OAuth: Google xếp `gmail.readonly` vào nhóm restricted. Tài liệu của Google nêu yêu cầu xác minh ứng dụng cho nhóm này và đánh giá bảo mật khi lưu hoặc truyền dữ liệu restricted qua máy chủ.

**Chọn IMAP** nếu bạn đã có thư viện phù hợp hoặc phải kết nối nhiều nhà cung cấp. Đổi lại, bạn vẫn cần xử lý nhãn Gmail, thư trùng qua các thư mục và lỗi xác thực.

**Chọn Mailera** nếu muốn agent dùng REST/MCP chung thay vì tự viết từng kết nối. Bài [kết nối các nhà cung cấp email hiện có với agent](https://mailera.app/blog/ket-noi-email-voi-ai-qua-rest-api-mcp) trình bày luồng nhiều nhà cung cấp. Mailera không tạo hộp thư hay địa chỉ email mới.

Nếu bạn cần kết nối cả Outlook, xem [hướng dẫn kết nối Outlook bằng OAuth qua Microsoft Graph](https://mailera.app/blog/ket-noi-outlook-bang-oauth); luồng đó khác với kết nối Gmail bằng mật khẩu ứng dụng.

Với tích hợp tự xây, hãy tính công sức theo đầu việc: cấp quyền, tải thư ban đầu, lưu trạng thái đồng bộ, phục hồi lỗi và thu hồi thông tin xác thực. Đừng ước lượng chỉ từ số dòng code lấy được thư đầu tiên.

## Kết nối Gmail với Mailera và đọc một thư

Bạn cần hộp thư của mình, vai trò Quản trị viên hoặc Trưởng nhóm trong Mailera, cùng tài khoản Google đã bật xác minh 2 bước và được phép tạo mật khẩu ứng dụng (app password). [Trang kết nối Gmail của Mailera](https://mailera.app/providers/gmail) mô tả luồng dành cho Gmail và Google Workspace. Nếu cần hướng dẫn riêng cho bước chuẩn bị này, xem [cách tạo mật khẩu ứng dụng Gmail và kết nối hộp thư](https://mailera.app/blog/tao-mat-khau-ung-dung-gmail).

1. Mở **Danh sách hộp thư** → **Thêm hộp thư**, chọn **Một hộp thư**.
2. Nhập Gmail vào **Địa chỉ email**. Kiểm tra nhà cung cấp được nhận diện; nếu cần, chọn tại **Hoặc chọn nhà cung cấp**, rồi nhấn **Tiếp tục**.
3. Làm theo [hướng dẫn mật khẩu ứng dụng của Google](https://support.google.com/accounts/answer/185833). Nếu tài khoản không có tùy chọn này, kiểm tra điều kiện tài khoản trước khi tiếp tục.
4. Trong **Thông tin kết nối**, nhập mật khẩu ứng dụng vào **Mật khẩu**, chọn **Nhóm quản lý**, rồi nhấn **Kiểm tra & kết nối**. Mailera đăng nhập thử, không gửi thư thật. Nếu nhận được nhưng kiểm tra gửi thất bại, có thể chọn **Lưu ở chế độ Chỉ nhận**.
5. Chờ tải thư lần đầu rồi chọn **Mở hộp thư** để kiểm tra. Thư được tải trong khoảng lưu trữ, mới nhất trước.
6. Trong **Cài đặt**, mở phần khóa API và chọn **Tạo key**. Giới hạn **Phạm vi hộp thư** về nhóm cần đọc và chỉ cấp `read`. Lưu khóa khi hộp thoại **Key đã tạo — sao chép ngay** xuất hiện.

![Màn hình kết nối Gmail trong Mailera với trường Mật khẩu và nút Kiểm tra & kết nối.](https://mailera.app/media/39e644d283f9e836/ket-noi-email-voi-ai-doc-hop-thu-hien-co-qua-rest-api-hoac-vi-1200.jpg)
_Trường Mật khẩu cần mật khẩu ứng dụng Google, không phải mật khẩu đăng nhập thông thường._

Mật khẩu ứng dụng xác thực kết nối Gmail → Mailera. Khóa API Mailera xác thực ứng dụng hoặc agent → Mailera. Quyền `read` của khóa Mailera không biến mật khẩu ứng dụng Google thành thông tin xác thực chỉ đọc.

Để gọi REST, đặt khóa vào biến môi trường `$MAILERA_API_KEY`. Lấy `id` hộp thư từ `GET /mailboxes` và đặt vào `$MAILBOX_ID`. Sau đó 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=1' \
  -H "Authorization: Bearer $MAILERA_API_KEY"
```

Nếu `data` có thư, lấy `data[0].id` làm `$MESSAGE_ID`, rồi đọc nội dung:

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

Nội dung nằm trong `data.body.text` và `data.body.html`. Cả hai yêu cầu đều dùng quyền `read`; xem [tài liệu cho nhà phát triển](https://mailera.app/developers) để xây phần gọi API của ứng dụng.

Nếu dùng Claude, Cursor hoặc VS Code, chọn **Sao chép cấu hình MCP** trong hộp thoại tạo khóa. Công cụ `get_message` cần `read`, còn `send_email` cần `send` riêng.

![Tạo khóa API Mailera giới hạn một nhóm hộp thư và chỉ có quyền đọc.](https://mailera.app/media/25741437a615ecdc/gmail-api-va-imap-chon-cach-doc-gmail-cho-ai-agent-read-key-vi-1200.jpg)
_Quyền read cho phép agent đọc thư; quyền gửi phải được cấp riêng._

## Những lỗi nào thường gặp khi cho agent đọc Gmail?

**Không thấy tùy chọn mật khẩu ứng dụng.** Google liệt kê các nguyên nhân có thể gặp: xác minh 2 bước chỉ dùng khóa bảo mật, tài khoản tổ chức hoặc Advanced Protection. Kiểm tra chính sách tài khoản; đừng tìm cách bỏ qua hạn chế của quản trị viên.

**Đăng nhập thất bại dù mật khẩu tài khoản đúng.** Trường **Mật khẩu** trong luồng Gmail này cần mật khẩu ứng dụng, không phải mật khẩu đăng nhập thông thường. Google cũng thu hồi mật khẩu ứng dụng khi bạn đổi mật khẩu tài khoản. Kiểm tra loại thông tin xác thực mà không ghi bí mật vào nhật ký.

**Số thư lệch khi cộng các thư mục.** Gmail biểu diễn nhãn như thư mục IMAP; cùng một thư có thể xuất hiện ở nhiều thư mục. Với tích hợp tự xây, kiểm tra ánh xạ nhãn và dùng định danh phù hợp để tránh đếm trùng.

**Thư mới chưa xuất hiện trong Mailera.** Kiểm tra trạng thái hộp thư và lần đồng bộ gần nhất. Kiểm tra nền chạy thường xuyên hơn khi hộp thư đang được dùng, thưa hơn khi ít hoạt động; hộp thư không hoạt động có thể ngủ rồi thức khi được dùng lại. Mailera không bảo đảm đồng bộ tức thời trong mọi trạng thái.

**Gmail API trả HTTP 404 khi đồng bộ lịch sử.** Theo [hướng dẫn đồng bộ Gmail](https://developers.google.com/workspace/gmail/api/guides/sync), nếu `startHistoryId` nằm ngoài khoảng lịch sử còn hiệu lực, ứng dụng phải đồng bộ đầy đủ lại, thay vì lặp mãi yêu cầu cũ.

## Làm sao cho agent đọc thư mà không được gửi?

Thư đến là dữ liệu không tin cậy, không phải lệnh. Agent không được làm theo nội dung yêu cầu đổi quy tắc, tiết lộ bí mật hoặc gọi công cụ ngoài nhiệm vụ. Đây là ranh giới cần giữ ngay cả khi thư có vẻ đến từ người quen.

Với Mailera, chỉ cấp `read`, giới hạn nhóm hộp thư, đặt **Thời hạn** và **Giới hạn IP (tuỳ chọn)** nếu phù hợp. Không cấp `send`, `move` hoặc `manage` cho nhiệm vụ chỉ đọc. Nếu sau này cho phép gửi, yêu cầu người dùng xác nhận trước mỗi lần gửi.

Không đặt mật khẩu ứng dụng, khóa API hoặc mã xác minh trong câu lệnh cho mô hình, ảnh chụp hay nhật ký. Xem thêm [thông tin bảo mật của Mailera](https://mailera.app/security).

Thu hồi khóa Mailera sẽ chặn các lệnh gọi bằng khóa đó ngay lập tức. Đây là lớp khác với mật khẩu ứng dụng Google dùng cho kết nối hộp thư; hãy chọn đúng lớp cần ngắt truy cập.

## Giới hạn cần biết trước khi chọn Mailera

Kết nối Gmail hiện dùng IMAP với mật khẩu ứng dụng, không phải Gmail API hay luồng OAuth Gmail. Nếu tài khoản không được phép tạo mật khẩu ứng dụng, bạn không thể dùng luồng này; Mailera không thay đổi được chính sách Google Workspace.

Gói miễn phí lưu thư trong 30 ngày. Nếu agent cần xử lý thư cũ hơn, hãy tính yêu cầu lưu trữ trước khi chọn cách kết nối.

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