Refresh token được dùng để lấy cặp access token và refresh token mới khi access token hiện tại hết hạn. Nó không phải khoá API Mailera: khoá API dùng để gọi Mailera, còn refresh token trong quy trình này dùng với Microsoft.
Cần chuẩn bị gì trước khi nhập token?
Mailera hỗ trợ Outlook.com, Hotmail và Microsoft 365 qua Microsoft Graph, bằng OAuth hoặc refresh token có sẵn. Bạn cần vai trò Admin hoặc Leader để thêm hộp thư; xem cách phân quyền quản lý hộp thư trong nhóm.
Định dạng Microsoft là email:password:refresh_token:client_id, mỗi hộp thư một dòng.
| Trường | Nội dung cần đối chiếu | Cách bảo vệ |
|---|---|---|
email | Địa chỉ hộp thư bạn muốn kết nối | Che khi chia sẻ ảnh hoặc báo lỗi |
password | Tên trường ở vị trí thứ hai trong định dạng nhập Microsoft | Giữ kín giá trị trong dòng nhập |
refresh_token | Token từ luồng OAuth của hộp thư và ứng dụng bạn quản lý | Không đưa vào nhật ký, ảnh chụp hoặc lời nhắc AI |
client_id | Application (client) ID của ứng dụng tương ứng | Đối chiếu với ứng dụng cấp token, không lấy từ ứng dụng khác |
Nếu bạn không biết cần điền gì vào trường password, chọn Đăng nhập Microsoft thay vì tự đoán.
Theo tài liệu refresh token của Microsoft, token gắn với một cặp người dùng và ứng dụng cụ thể. Vì vậy, chỉ có token chưa có nghĩa là bạn đã có đúng bộ thông tin kết nối.
Microsoft định nghĩa client_id là Application (client) ID được cấp khi đăng ký ứng dụng trong Microsoft Entra. Bạn có thể đối chiếu trường này trong tài liệu luồng OAuth authorization code.
Nếu bạn không có bộ thông tin nhập rõ ràng, chọn Đăng nhập Microsoft để đi qua luồng chấp thuận OAuth. Xem trang kết nối Microsoft của Mailera. Các bước đăng nhập được trình bày trong hướng dẫn kết nối Outlook bằng OAuth qua Microsoft Graph.
Các bước nhập refresh token vào Mailera
Bắt đầu bằng một hộp thư thử của bạn để dễ đối chiếu kết quả và tránh xử lý nhầm địa chỉ đã tồn tại.
- Mở Danh sách hộp thư → Thêm hộp thư → Dán hàng loạt.
- Chuẩn bị dòng nhập theo thứ tự
email:password:refresh_token:client_id. Mỗi hộp thư nằm trên một dòng. Mailera hỗ trợ dấu hai chấm, dấu|, dấu chấm phẩy hoặc Tab làm dấu phân cách; bạn cũng có thể tải tệp.txt. - Chọn nhóm hộp thư đích. Nếu địa chỉ đã tồn tại, chọn cách bỏ qua hoặc ghi đè. Với lần thử đầu, nên bỏ qua để tránh thay đổi một kết nối đang dùng; đừng chọn ghi đè chỉ để làm mất thông báo trùng.
- Chọn Bắt đầu nhập. Trang tiến trình phân loại kết quả thành công, lỗi và bỏ qua. Xem kết quả của dòng vừa nhập trước khi thêm các hộp thư khác.
- Xoá bản sao tạm chứa bí mật sau khi hoàn tất. Không lưu tệp nhập trong kho mã hoặc thư mục chia sẻ.
Nếu dòng nhập báo lỗi, giữ lại thông báo đã che bí mật để xử lý, không gửi nguyên dòng cho người hỗ trợ. Trang tiến trình có chức năng xuất lỗi thành CSV; hãy mở và kiểm tra nội dung tệp trước khi chia sẻ.
Với quy trình tự động hoá, POST /mailboxes/import yêu cầu quyền import. Bạn có thể theo dõi tiến trình và kết quả từng dòng bằng GET /mailboxes/import với tham số job_id, cũng dùng quyền import. Xem cách tích hợp trong tài liệu API Mailera.
Làm sao biết hộp thư đã kết nối và đọc thư được?
Đừng dừng ở kết quả nhập thành công. Hãy kiểm tra riêng ba việc: dữ liệu đã được nhập, Microsoft còn cho phép đăng nhập, và thư đã đọc được trong Mailera.
Gọi GET /mailboxes và đối chiếu email, provider, group_id, status, last_sync_at trong từng phần tử data. Sau đó mở một thư thử không nhạy cảm mà bạn đã thấy trong Outlook, so sánh tiêu đề và nội dung. Không dùng thư chứa mã xác minh thật để minh hoạ.
Nếu kiểm tra bằng API, các endpoint sau đều dùng quyền read:
| Cần kiểm tra | Endpoint | Nội dung cần xem |
|---|---|---|
| Hộp thư đã có trong Mailera | GET /mailboxes | email, provider, group_id, status |
| Đăng nhập Microsoft còn hoạt động | GET /mailboxes/{id}/status | Kết quả kiểm tra đăng nhập trực tiếp |
| Thư đã xuất hiện | GET /mailboxes/{id}/messages | Đối chiếu subject, received_at, folder |
| Nội dung thư đọc được | GET /mailboxes/{id}/messages/{msgId} | Đối chiếu body.text hoặc body.html |
Ở chi tiết hộp thư, bạn cũng có thể xem last_sync_at, error_code và error để biết nên kiểm tra tiếp phần nào. Trạng thái hộp thư và thời điểm đồng bộ không thay thế việc mở thử một thư. Sau bước này, bạn có thể tiếp tục với quy trình đọc và xử lý email qua API cho AI agent.
Những lỗi hay gặp khi nhập token Outlook là gì?
Phân biệt lỗi dòng nhập với lỗi xác thực Microsoft trước khi thay thông tin kết nối.
| Triệu chứng | Điều cần kiểm tra | Bước tiếp theo |
|---|---|---|
| Dòng nhập bị báo lỗi | Thứ tự trường, dấu phân cách, token bị cắt hoặc xuống dòng khi sao chép | Đối chiếu lại dòng gốc trong môi trường riêng tư |
| Địa chỉ bị bỏ qua | Hộp thư đã tồn tại và bạn chọn bỏ qua | Tìm kết nối hiện có trước khi nhập lại |
| Dòng đúng định dạng nhưng đăng nhập thất bại | Token còn hiệu lực không; client_id có thuộc ứng dụng tương ứng không | Kiểm tra bộ thông tin ứng dụng hoặc đăng nhập Microsoft lại |
| Đăng nhập được nhưng không đọc được thư | Quyền truy cập Microsoft Graph đã được chấp thuận chưa | Kiểm tra quyền với người quản lý ứng dụng hoặc quản trị viên |
| Thư thử chưa xuất hiện | Thư mục đang xem và lần đồng bộ gần nhất | Đối chiếu thư trong Outlook rồi kiểm tra lại Mailera |
Khi rà soát dòng nhập, để ý khoảng trắng thừa hoặc ký tự xuống dòng lẫn vào khi sao chép. Đừng tự sửa các ký tự bên trong token; hãy đối chiếu với nguồn lưu an toàn của bạn.
Nếu thông báo từ Microsoft có invalid_grant, đừng mặc định rằng lỗi này chỉ do refresh token Outlook hết hạn. Microsoft dùng lỗi này cho thông tin xác thực không hợp lệ, không phân tích được, bị thiếu hoặc không sử dụng được. interaction_required có nghĩa là yêu cầu cần người dùng tương tác, chẳng hạn thực hiện thêm bước xác thực. Đối chiếu theo tài liệu lỗi xác thực Microsoft.
Quyền API Mailera và quyền Microsoft Graph là hai lớp khác nhau. Cấp read cho khoá Mailera không cấp thêm quyền cho ứng dụng tại Microsoft. Microsoft Graph yêu cầu người dùng hoặc quản trị viên chấp thuận các quyền cần thiết; các quyền giới hạn cho quản trị viên cần sự chấp thuận của quản trị viên tổ chức.
Refresh token Outlook có dùng được mãi không?
Không. Token có thể hết hiệu lực hoặc bị dịch vụ đăng nhập Microsoft thu hồi trước khi hết hạn. Khi token bị thu hồi, Microsoft khuyến nghị đưa người dùng trở lại luồng đăng nhập tương tác để xác thực và nhận token mới.
Lấy token mới không tự động thu hồi refresh token cũ. Microsoft khuyến nghị xoá an toàn token cũ sau khi nhận token mới. Nếu bạn nghi token đã lộ, đừng coi thao tác làm mới token là đủ để xử lý sự cố.
Hãy dựa vào kết quả đăng nhập và thông báo lỗi thực tế để quyết định khi nào cần kết nối lại.
Bảo vệ token và xử lý khi nghi bị lộ thế nào?
Mailera mã hoá token gửi qua phần dán hàng loạt trước khi lưu và không hiển thị lại. Bạn vẫn cần bảo vệ các bản sao trước và sau khi nhập; xem thêm thông tin bảo mật của Mailera.
Không dán token vào công cụ kiểm tra bên ngoài, cuộc trò chuyện hỗ trợ hoặc AI. Che cả mật khẩu và khoá API trong ảnh chụp. Khi báo lỗi, chỉ gửi thông báo đã loại bỏ bí mật và mô tả bước thao tác gây lỗi.
Nếu nghi token bị lộ, thu hồi token phía Microsoft theo loại tài khoản và ứng dụng của bạn, rồi kết nối lại. Đừng coi việc xoá hộp thư trong Mailera là bước thay thế cho thu hồi token tại Microsoft. Với tài khoản B2B, Microsoft yêu cầu thu hồi token tại tenant gốc, không phải tenant tài nguyên.
Khi kết nối hộp thư có sẵn với 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ộ bí mật hoặc thay đổi quyền. Chỉ cấp read và phạm vi hộp thư cần thiết cho agent đọc thư; không cấp import hoặc manage. Nếu cho phép gửi, yêu cầu người dùng xác nhận trước khi gửi.
Mailera không làm gì trong quy trình này?
Mailera kết nối các hộp thư bạn đã có, không tạo hộp thư hoặc địa chỉ email mới. Nhập token không thay thế sự chấp thuận quyền truy cập của Microsoft và không bảo đảm token hoạt động vĩnh viễn.
Hộp thư Microsoft dùng OAuth trong quy trình này, không kết nối bằng mật khẩu ứng dụng. Nếu không rõ ứng dụng nào đã cấp token hoặc không có bộ thông tin phù hợp, dùng Đăng nhập Microsoft thay vì thử ghép token với một client_id khác.
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ư
