Kết nối Outlook bằng OAuth và kiểm tra đọc thư qua Mailera

OAuth, Microsoft Graph và khóa API Mailera khác nhau ở đâu?

OAuth là cơ chế cấp quyền cho ứng dụng truy cập dữ liệu. Microsoft Graph là API truy cập dữ liệu Microsoft, trong đó có thư Outlook. Khóa API Mailera dùng ở lớp khác: cho phép ứng dụng của bạn gọi Mailera sau khi hộp thư đã kết nối.

Theo tài liệu truy cập Graph thay mặt người dùng, ứng dụng gọi Graph cần access token từ Microsoft identity platform. Nếu tự tích hợp Graph, bạn phải đăng ký ứng dụng với Microsoft Entra ID. Đó là quy trình khác với việc bắt đầu bằng thẻ đăng nhập Microsoft trong Mailera.

Tài liệu liệt kê thư của Microsoft Graph mô tả endpoint GET /me/messages. Các lệnh bên dưới gọi API Mailera, không gọi endpoint này. Đừng dùng khóa API Mailera làm token cho Graph.

OAuth cũng không đồng nghĩa với Graph: OAuth cho IMAP, POP và SMTP dùng phạm vi quyền và giao thức riêng. Không trộn hướng dẫn đó vào kết nối Microsoft qua Graph. Nếu đang cấu hình ứng dụng dùng IMAP hoặc SMTP, xem bài cài đặt IMAP và SMTP của Outlook.

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

Dùng hộp thư của bạn hoặc hộp thư bạn được phép quản lý. Xác định đó là tài khoản Outlook.com cá nhân hay tài khoản Microsoft 365 của cơ quan, trường học để biết ai có thể phê duyệt quyền truy cập.

Trong Mailera, chỉ quản trị viên (Admin) hoặc trưởng nhóm (Leader) được thêm hộp thư. Nếu Microsoft yêu cầu quản trị viên phê duyệt, hãy chuyển yêu cầu cho quản trị viên tổ chức. Microsoft quy định người dùng hoặc quản trị viên phải cấp các quyền cần thiết; quyền bị giới hạn cho quản trị viên cần được xử lý theo hướng dẫn cấp quyền OAuth của Microsoft.

Mailera kết nối hộp thư có sẵn, không tạo hộp thư hay địa chỉ Outlook mới. Xem thêm bài Kết nối nhà cung cấp email hiện có với agent.

Kết nối Outlook với Mailera theo những bước nào?

Kết nối Microsoft của Mailera hỗ trợ Outlook.com, Hotmail và Microsoft 365. Kết nối này dùng OAuth qua Microsoft Graph, không dùng mật khẩu ứng dụng. Mailera không phải đối tác chính thức của Microsoft; việc cấp quyền được xử lý tại Microsoft.

1. Mở Danh sách hộp thư, chọn Thêm hộp thư. Trang này có các thẻ Một hộp thư, Đăng nhập Microsoft và Dán hàng loạt.
2. Chọn thẻ Đăng nhập Microsoft để đăng nhập tương tác theo hướng dẫn này.
3. Tại Microsoft, đăng nhập đúng tài khoản cần kết nối. Đọc yêu cầu cấp quyền và xác nhận nếu phù hợp. Nếu cần phê duyệt quản trị viên, xử lý yêu cầu đó trước khi tiếp tục.
4. Trở lại Mailera, mở Danh sách hộp thư và đối chiếu địa chỉ, trạng thái của hộp thư vừa kết nối. Khi kết nối thành công, Mailera bắt đầu tải thư lần đầu. Cách tạo khóa API và các lệnh kiểm tra trạng thái, đọc thư nằm ở phần tiếp theo.
5. Gửi một thư thử không chứa dữ liệu nhạy cảm đến hộp thư của bạn, với tiêu đề dễ nhận ra như “Thử đọc thư Outlook”. Mở Hộp thư chung, chọn đúng hộp thư và tìm thư đó.

Ở bước cuối, đối chiếu cả tiêu đề lẫn người gửi. Hộp thư xuất hiện trong danh sách không có nghĩa là thư thử đã tải về. Nếu chưa thấy thư, hãy kiểm tra thư mục và tiến trình tải thư trước khi đăng nhập lại.

Làm sao kiểm tra ứng dụng đã đọc được thư?

Tạo khóa API riêng cho ứng dụng đọc thư. Trong Cài đặt, mở tab API key và chọn Tạo key. Điền Tên gợi nhớ, chọn Phạm vi hộp thư là nhóm chứa hộp thư thử, rồi chỉ cấp quyền đọc (read). Quản trị viên có thể chọn tất cả nhóm, nhưng bài thử này không cần phạm vi rộng như vậy.

Khi thấy 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óa chỉ được hiển thị một lần; không đưa vào mã nguồn, ảnh chụp hay nhật ký. Nếu dùng với AI agent qua MCP, bạn cũng có thể chọn Sao chép cấu hình MCP ngay trong hộp thoại này. Bài các công cụ MCP của Mailera theo từng tác vụ giúp bạn chọn công cụ đọc thư phù hợp.

Phần dành cho nhà phát triển của Mailera là nơi tham khảo khi đưa các yêu cầu dưới đây vào ứng dụng.

Các lệnh dưới đây dùng biến môi trường $MAILERA_API_KEY chứa khóa vừa tạo. Sau bước đầu, đặt $MAILBOX_ID bằng id của đúng hộp thư. Không dùng địa chỉ email thay cho ID.

1. Tìm hộp thư cần đọc

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

Trong mảng data, đối chiếu trường email để lấy id của hộp thư đó. Bạn có thể thêm ?provider=microsoft vào URL trên để chỉ liệt kê hộp thư Microsoft. Trường provider trả về microsoft, còn protocol trả về graph cho các hộp thư này. Nếu danh sách có nhiều trang, dùng limit và offset để tìm tiếp.

2. Kiểm tra đăng nhập còn hoạt động

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

Với hộp thư Microsoft, endpoint này kiểm tra trực tiếp khả năng đăng nhập; với các nhà cung cấp khác, kết quả dựa trên lần đồng bộ gần nhất. Dùng nó để tách lỗi đăng nhập khỏi chuyện thư chưa xuất hiện trong danh sách.

3. Liệt kê thư trong hộp thư đến

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

Tìm lại thư thử đã xem trong Hộp thư chung, đối chiếu subject, from.address và received_at trong data. Trường folder cho biết thư mục của thư. Nếu có next_cursor, dùng giá trị đó làm tham số cursor để đọc trang tiếp theo.

Danh sách rỗng chưa đủ để kết luận OAuth bị lỗi. Có thể bạn đang xem sai hộp thư, sai thư mục, hoặc thư chưa tải về. Đổi folder=inbox thành folder=junk để kiểm tra Thư rác khi cần.

4. Kiểm tra cả nội dung thư

Đặt $MESSAGE_ID bằng id của thư thử vừa tìm được:

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

Đối chiếu data.body.text hoặc data.body.html với nội dung thư thử. Đây là bước kiểm tra ứng dụng đọc được nội dung, thay vì chỉ thấy tiêu đề và đoạn xem trước trong danh sách.

Những lỗi hay gặp khi kết nối Outlook là gì?

Đăng nhập Microsoft thành công chưa có nghĩa ứng dụng đang dùng đúng khóa Mailera, đúng nhóm hộp thư và đúng thư mục. Kiểm tra theo lớp sẽ tránh việc cấp quyền lại khi lỗi nằm ở yêu cầu API.

Đừng tăng quyền khóa chỉ để thử xem lỗi có hết không. Các yêu cầu đọc hộp thư, trạng thái, danh sách và nội dung thư ở trên đều dùng quyền read.

Cấp quyền thế nào để ứng dụng hoặc agent đọc thư an toàn?

Microsoft khuyến nghị cấp quyền tối thiểu cần thiết. Với khóa API Mailera trong bài này, giữ quyền read và giới hạn đúng nhóm hộp thư; không thêm send hoặc manage cho tác vụ chỉ đọc.

Nếu ứng dụng là AI agent, coi 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ộ khóa, đổi cấu hình hay thực hiện hành động ngoài yêu cầu của người dùng. Nếu mở rộng sang gửi thư, yêu cầu người dùng xác nhận trước khi gửi. Xem thêm thông tin bảo mật của Mailera.

Khi ngừng sử dụng, phân biệt các lớp truy cập:

• Thu hồi khóa API Mailera: các yêu cầu dùng khóa đó bị từ chối ngay.
• Xóa kết nối hộp thư trong Mailera: đây là thao tác quản lý hộp thư, khác với thu hồi một khóa API.
• Quyền đã đồng ý tại Microsoft: thuộc lớp cấp quyền Microsoft, không nên coi việc thu hồi khóa Mailera là đã xử lý lớp này.

Nếu cần dừng ứng dụng đọc thư ngay qua khóa đang dùng, thu hồi khóa đó trước. Không thêm quyền quản lý hộp thư vào khóa chỉ đọc chỉ để phục vụ việc dọn kết nối.

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

Mailera nhận thư Microsoft qua thông báo thay đổi của Graph, kèm kiểm tra nền định kỳ dự phòng. Đây là cơ chế theo dõi thư mới, khác với OAuth dùng để cấp quyền truy cập hộp thư.

Trong bước Kiểm tra & kết nối, mục Theo dõi liên tục là kết quả kiểm tra khả năng theo dõi thư: Có — thư mới về sau vài giây khi hộp đang dùng hoặc Không — dùng quét 2 phút khi hộp đang dùng. Với Microsoft, cơ chế theo dõi liên tục là thông báo thay đổi của Graph nói trên. Mốc quét 2 phút trên giao diện áp dụng khi không có theo dõi liên tục và hộp thư đang dùng, không phải lịch kiểm tra nền cố định cho mọi hộp thư. Các lần kiểm tra nền diễn ra thưa hơn với hộp thư ít hoạt động; hộp thư không hoạt động có thể chuyển sang trạng thái ngủ.

Mailera không cam kết nhận thư tức thì tuyệt đối. Khi chưa thấy thư mới, hãy kiểm tra khả năng đăng nhập bằng /status rồi kiểm tra thư đã tải bằng endpoint danh sách thư.