---
title: "Kết nối Outlook bằng OAuth và kiểm tra đọc thư qua Mailera"
description: "Hướng dẫn kết nối Outlook bằng OAuth qua Microsoft Graph trong Mailera, tạo khóa API quyền đọc và kiểm tra hộp thư, trạng thái đăng nhập, danh sách thư."
url: https://mailera.app/blog/ket-noi-outlook-bang-oauth
published: 2026-10-25
updated: 2026-10-25
---

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

Đăng nhập Microsoft để kết nối hộp thư có sẵn, rồi dùng khóa API Mailera kiểm tra trạng thái và đọc thư. Không cần mật khẩu ứng dụng cho kết nối Microsoft.

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

| Thành phần | Vai trò | Dùng ở đâu? |
| --- | --- | --- |
| OAuth | Người dùng cấp quyền truy cập | Khi đăng nhập và đồng ý tại Microsoft |
| Microsoft Graph | Truy cập dữ liệu hộp thư Microsoft | Giữa Mailera và Microsoft |
| Khóa API Mailera | Xác thực ứng dụng gọi Mailera | Trong header `Authorization` của API Mailera |

Theo [tài liệu truy cập Graph thay mặt người dùng](https://learn.microsoft.com/en-us/graph/auth-v2-user), ứ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](https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0) 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](https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth) 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](https://mailera.app/blog/cai-dat-imap-outlook-smtp).

![Hai lớp truy cập: cấp quyền OAuth tại Microsoft và gọi Mailera bằng khóa API quyền read.](https://mailera.app/media/9e624633bec3c6e7/ket-noi-outlook-bang-oauth-va-kiem-tra-doc-thu-qua-mailera-vi-1200.jpg)
_Quyền Microsoft và khóa API Mailera phục vụ hai kết nối khác nhau._

## 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](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow).

[Mailera](https://mailera.app/product) 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](https://mailera.app/blog/ket-noi-email-voi-ai-qua-rest-api-mcp).

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

[Kết nối Microsoft của Mailera](https://mailera.app/providers/microsoft) 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ư đó.

![Thẻ Đăng nhập Microsoft trên trang Thêm hộp thư của Mailera.](https://mailera.app/media/39e644d283f9e836/ket-noi-email-voi-ai-doc-hop-thu-hien-co-qua-rest-api-hoac-vi-1200.jpg)
_Chọn Đăng nhập Microsoft để bắt đầu kết nối OAuth._

Ở 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ụ](https://mailera.app/blog/cong-cu-mcp-mailera) 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](https://mailera.app/developers) là nơi tham khảo khi đưa các yêu cầu dưới đây vào ứng dụ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/46ed59d0a6a38c95/ket-noi-outlook-bang-oauth-va-kiem-tra-doc-thu-qua-mailera-vi-1200.jpg)
_Khóa dùng để kiểm tra đọc thư chỉ cần quyền read và phạm vi nhóm phù hợp._

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

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

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

```bash
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:

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

| Dấu hiệu | Điều cần kiểm tra | Bước tiếp theo |
| --- | --- | --- |
| Không thêm được hộp thư | Vai trò trong Mailera | Nhờ Admin hoặc Leader thực hiện kết nối |
| Microsoft yêu cầu phê duyệt | Quyền cần quản trị viên chấp thuận | Chuyển yêu cầu cho quản trị viên tổ chức |
| Hộp thư xuất hiện nhưng sai địa chỉ | Tài khoản vừa đăng nhập tại Microsoft | Đối chiếu địa chỉ và kết nối tài khoản cần dùng |
| Kết nối được nhưng chưa thấy thư | Trạng thái đăng nhập, thư mục, lần đồng bộ | Gọi `/status`, kiểm tra `inbox` và `junk` |
| API từ chối truy cập | Khóa, quyền `read`, phạm vi nhóm | Kiểm tra header và cấu hình khóa đang dùng |
| Có tiêu đề nhưng chưa kiểm tra được nội dung | Bạn mới gọi endpoint danh sách | Lấy `id` của thư rồi gọi endpoint đọc một thư |

Đừ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](https://learn.microsoft.com/en-us/graph/permissions-reference). 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](https://mailera.app/security).

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

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