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

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ó 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 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ư.

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 có trang riêng cho từng dịch vụ.

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

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

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

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.

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:

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 để tìm đúng hộp.

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=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:

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

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.

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