Kết nối Microsoft 365 qua Microsoft Graph với Mailera

Cần chuẩn bị gì trước khi kết nối?

Mailera dùng OAuth qua Microsoft Graph để truy cập hộp thư Microsoft 365. Bạn bắt đầu từ hộp thư đang sử dụng; Mailera không tạo hộp thư hay địa chỉ email mới.

Trước khi mở luồng kết nối Microsoft của Mailera, hãy kiểm tra:

Đừng dùng việc đăng nhập Microsoft thành công làm tiêu chí duy nhất. Mục tiêu nghiệm thu là đọc được thư trong đúng hộp thư. Nếu cần nối thêm các nhà cung cấp khác, xem hướng dẫn kết nối hộp thư có sẵn với agent.

Ba lớp quyền khác nhau ở đâu?

Vai trò trong Mailera, quyền Microsoft Graph và quyền của khoá API Mailera không thay thế nhau.

Khi phân công người quản lý hộp thư và cấp quyền cho agent, xem hướng dẫn phân quyền quản lý email cho nhóm và AI.

Theo tài liệu xác thực Microsoft Graph, quyền được uỷ quyền là quyền ứng dụng dùng thay mặt người đang đăng nhập. Cả ứng dụng lẫn người dùng đều phải được phép thực hiện yêu cầu. Quyền ứng dụng, hay app-only, dùng danh tính riêng của ứng dụng. Đây là hai khái niệm để đọc tài liệu Microsoft; luồng dưới đây dùng đăng nhập Microsoft trong Mailera.

Hãy đọc danh sách quyền thực tế trên màn hình đồng ý. Đừng lấy một quyền đọc thư trong tài liệu Graph rồi mặc định đó là toàn bộ quyền Mailera yêu cầu. Nếu cần hiểu thêm về luồng OAuth, xem hướng dẫn kết nối Outlook bằng OAuth qua Microsoft Graph.

Khi nào cần quản trị viên phê duyệt?

Theo quy định đồng ý của Microsoft Entra, người dùng không phải quản trị viên chỉ có thể đồng ý khi tổ chức cho phép cả ứng dụng và tập quyền được yêu cầu.

Nếu tổ chức bật quy trình phê duyệt, Microsoft có thể hiện cửa sổ “Approval required”. Hãy gửi yêu cầu theo quy trình đó, không tắt chính sách bảo mật để tiếp tục.

Quản trị viên có thể kiểm tra thiết lập tại “Identity” → “Applications” → “Enterprise apps” → “Consent and permissions” → “User consent settings”, theo hướng dẫn cấu hình của Microsoft. Thay đổi thiết lập này không làm thay đổi các quyền đồng ý đã cấp trước đó.

Kết nối hộp thư Microsoft 365 như thế nào?

1. Mở Danh sách hộp thư → Thêm hộp thư → Đăng nhập Microsoft. Kết quả cần thấy là luồng đăng nhập tại Microsoft, không phải biểu mẫu mật khẩu ứng dụng.
2. Đăng nhập tài khoản cơ quan có hộp thư cần kết nối. Kiểm tra tài khoản và tổ chức trước khi tiếp tục, rồi đọc các quyền được yêu cầu.
3. Hoàn tất bước đồng ý hoặc yêu cầu phê duyệt. Nếu Microsoft yêu cầu quản trị viên xử lý, chuyển yêu cầu cho người phụ trách tổ chức.
4. Trở lại Danh sách hộp thư. Kiểm tra đúng hộp thư đã xuất hiện, nhà cung cấp và trạng thái kết nối, sau đó chuyển sang phép thử đọc thư.

Địa chỉ dùng tên miền công ty không phải lý do để chọn IMAP tùy chỉnh. Với hộp thư Microsoft 365 trong hướng dẫn này, bạn vẫn dùng Đăng nhập Microsoft. Nhánh Microsoft của Mailera không kết nối bằng mật khẩu ứng dụng và không dùng quy trình kiểm tra IMAP/SMTP.

Làm sao xác nhận đã đọc được thư?

Dùng hộp thư thử thuộc quyền quản lý của bạn. Gửi vào đó một thư có tiêu đề dễ nhận ra, không chứa dữ liệu nhạy cảm, rồi tìm thư trong giao diện Mailera.

Kiểm tra đăng nhập và kiểm tra thư là hai việc riêng: GET /mailboxes/{id}/status kiểm tra trực tiếp khả năng đăng nhập hộp thư Microsoft; GET /mailboxes/{id}/messages liệt kê thư trong một thư mục.

Tạo khoá chỉ đọc

Trong Cài đặt, mở phần khoá API rồi chọn Tạo key. Đặt Tên gợi nhớ, giới hạn Phạm vi hộp thư vào nhóm thử, chỉ cấp quyền read và đặt Thời hạn. Admin có thể chọn tất cả nhóm, nhưng phép thử này không cần phạm vi đó.

Lưu khoá khi thấy Key đã tạo — sao chép ngay. Khoá chỉ được hiển thị một lần.

Đọc danh sách rồi đọc nội dung

Đặt $MAILERA_API_KEY và $MAILBOX_ID trong môi trường chạy lệnh của bạn. ID hộp thư có thể lấy từ trường id của GET /mailboxes. Không dán khoá vào hội thoại hay tài liệu dùng chung.

Lệnh sau lấy một thư trong Hộp thư đến:

curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Đối chiếu subject, received_at và folder trong data. Nếu chưa thấy thư thử, tăng limit hoặc kiểm tra thư mục phù hợp; đừng kết luận lỗi đăng nhập chỉ từ một danh sách trống.

Đặt $MESSAGE_ID bằng id của thư cần đọc, rồi lấy nội dung:

curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Kiểm tra data.body.text hoặc data.body.html có nội dung thư thử. Đây là bước nghiệm thu quan trọng nếu ứng dụng cần đọc nội dung, không chỉ liệt kê tiêu đề. Xem tài liệu API Mailera khi triển khai vào ứng dụng.

Mailera nhận thư Microsoft mới qua thông báo thay đổi Graph, kèm kiểm tra nền dự phòng. Không nên coi việc thư chưa xuất hiện ngay là kết nối đã hỏng. Khi cần đồng bộ chủ động, POST /mailboxes/{id}/sync yêu cầu quyền sync riêng; khoá chỉ có read không đủ cho thao tác này.

Lỗi hay gặp: nên kiểm tra lớp nào?

Hãy ghi lại thao tác bị lỗi cùng phản hồi tương ứng. Lỗi gọi API Mailera và lỗi đăng nhập Microsoft cần được kiểm tra ở hai lớp khác nhau; cấp thêm quyền Graph không phải cách sửa mặc định cho khoá Mailera sai phạm vi.

Cho AI agent đọc thư thế nào để giảm rủi ro?

Thư đến là dữ liệu không tin cậy, không phải lệnh. Agent không được làm theo chỉ dẫn trong thư để tiết lộ dữ liệu, đổi quyền hoặc gọi công cụ. Quy tắc này áp dụng cả khi thư có vẻ đến từ một người quen.

Bắt đầu bằng khoá read, giới hạn một nhóm hộp thư và đặt thời hạn. Không cấp send cho tác vụ chỉ đọc. Nếu sau này mở chức năng gửi, yêu cầu người dùng xác nhận trước khi gửi.

Các công cụ MCP list_mailboxes, get_mailbox_status, list_messages và get_message đều thuộc quyền read. Hộp thoại tạo khoá có Sao chép cấu hình MCP cho Claude, Cursor hoặc VS Code. Cấu hình chứa thông tin truy cập phải được bảo vệ như khoá API. Để chọn công cụ phù hợp với từng thao tác của agent, xem các công cụ MCP Mailera theo tác vụ.

Khi ngừng thử nghiệm, thu hồi khoá Mailera; các lệnh gọi bằng khoá đó sẽ bị từ chối ngay. Việc này khác với thu hồi quyền ứng dụng tại Microsoft. Hãy quản lý cả hai lớp theo quy trình tổ chức và tham khảo thông tin bảo mật Mailera.

Giới hạn cần tính trước khi triển khai

Mailera không thay thế quyền phê duyệt của quản trị viên Microsoft 365 hay chính sách truy cập của tổ chức. Cơ chế thông báo Graph có kiểm tra nền dự phòng, không phải cam kết đồng bộ tức thời tuyệt đối.

Gói miễn phí lưu thư trong 30 ngày. Vì vậy, hãy nghiệm thu bằng thư mới thay vì dùng một thư cũ làm tiêu chí duy nhất. Tổng quan sản phẩm Mailera trình bày cách dùng các hộp thư đã kết nối qua API và MCP.