Gmail API và IMAP: chọn cách đọc Gmail cho AI 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. Đâ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.

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

Theo tài liệu OAuth cho Gmail IMAP, 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 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 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, 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 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; 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 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ư.

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. 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ậ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:

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:

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 để 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.

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, 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.

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.