Lỗi đồng bộ email: kiểm tra và khôi phục hộp thư trong Mailera

Hộp thư không cập nhật thì kiểm tra ở đâu trước?

Chọn một thư cụ thể để đối chiếu bằng người gửi, tiêu đề và thời điểm nhận. Mở web của nhà cung cấp, tìm trong cả Hộp thư đến lẫn Thư rác. Nếu chưa thấy thư tại nguồn, đừng bắt đầu bằng việc chạy đồng bộ liên tục trong Mailera.

Bài này xử lý hộp thư đã kết nối vào hộp thư hợp nhất của Mailera, không hướng dẫn sửa ứng dụng Outlook trên máy tính. Đồng bộ ở đây là cập nhật dữ liệu từ hộp thư nhà cung cấp vào Mailera; ứng dụng xử lý dữ liệu đó là bước riêng.

Xem quy trình vận hành tại vận hành hộp thư hợp nhất cho AI agent.

Kiểm tra trạng thái hộp thư trước khi đồng bộ

1. Xác định đúng hộp thư. Mở Danh sách hộp thư, xem bộ đếm thư chưa đọc ở Hộp thư đến và Thư rác của hộp thư cần kiểm tra. Các bộ đếm này giúp bạn tránh chỉ nhìn một thư mục.

Nếu dùng API, lấy id từ GET /mailboxes, rồi lưu vào biến môi trường $MAILBOX_ID. Khoá đặt trong $MAILERA_API_KEY. Đọc chi tiết hộp thư qua GET /mailboxes/{id} bằng quyền read:

curl --silent --show-error \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID" \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Từ phản hồi, ghi lại nhà cung cấp ở data.provider, trạng thái ở data.status và lần đồng bộ gần nhất ở data.last_sync_at. Lưu thêm data.error_code, data.error và đối tượng data.sync để so sánh sau. Phản hồi cũng có danh sách folders và bộ đếm thư.

2. Kiểm tra khả năng đăng nhập. Endpoint sau cần quyền read:

curl --silent --show-error \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/status" \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Với Microsoft, phép kiểm tra đăng nhập được thực hiện 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, không phải một lần đăng nhập thử mới.

Nếu hộp thư bị tạm dừng, xử lý việc bật lại riêng. API hỗ trợ thao tác này qua PATCH /mailboxes/{id} với quyền manage; xem cấu trúc yêu cầu trong tài liệu API Mailera. Không dùng việc gọi /sync thay cho thao tác bật lại.

Outlook hoặc Gmail lỗi xác thực thì xử lý thế nào?

Với Outlook.com, Hotmail và Microsoft 365, ưu tiên kết nối lại bằng OAuth theo hướng dẫn kết nối Microsoft. Mailera dùng Microsoft Graph cho các hộp thư này, không dùng mật khẩu ứng dụng. Nếu cần xem lại quy trình kết nối, tham khảo cách kết nối hộp thư đầu tiên.

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. Microsoft cũng mô tả cơ chế lifecycle notifications khi ứng dụng mất subscription hoặc bỏ lỡ thông báo trong tài liệu thông báo thay đổi Outlook. Vì vậy, hãy kiểm tra dữ liệu thư thực tế, không chỉ nhìn nhật ký sự kiện.

Với Gmail kết nối vào Mailera, kết nối dùng mật khẩu ứng dụng (app password), cần xác minh 2 bước và được quản trị viên cho phép. Theo tài liệu mật khẩu ứng dụng của Google, đổi mật khẩu Tài khoản Google sẽ thu hồi các mật khẩu ứng dụng. Nếu lỗi xuất hiện sau lần đổi mật khẩu, kiểm tra mật khẩu ứng dụng trước khi chạy đồng bộ lại.

Chạy đồng bộ lại bằng REST hoặc MCP

3. Giới hạn khoá API. Trong Cài đặt, mở phần khoá API và chọn Tạo key. Đặt Phạm vi hộp thư vào đúng nhóm cần xử lý, chỉ cấp read và sync cho quy trình này. Không thêm send hoặc manage nếu không dùng đến.

4. Yêu cầu đồng bộ hộp thư. Lệnh sau cần quyền sync:

curl --silent --show-error -X POST \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/sync" \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Endpoint yêu cầu đồng bộ ngay và cũng đánh thức hộp thư đang ngủ. Mailera kiểm tra nền thường xuyên hơn với hộp thư đang được sử dụng, ít hơn với hộp thư nhàn rỗi; hộp thư không hoạt động có thể ngủ. Vì vậy, không nên coi nhịp kiểm tra nền là cố định hoặc kỳ vọng đồng bộ tức thời tuyệt đối.

Nếu dùng MCP, công cụ tương ứng là sync_mailbox, cũng cần quyền sync. Chọn đúng hộp thư theo lược đồ công cụ trong trình khách; xem các công cụ MCP Mailera theo tác vụ để phân biệt thao tác đọc, đồng bộ và gửi.

Sau khi gửi yêu cầu, chuyển sang kiểm tra thư. Đừng coi phản hồi của lệnh đồng bộ là bằng chứng thư đã cập nhật xong, cũng đừng đặt vòng lặp gọi lại liên tục. Khi đăng nhập còn lỗi, xử lý xác thực trước.

Làm sao xác nhận quy trình đã hoạt động trở lại?

5. Đọc lại thư trong đúng thư mục. Ví dụ kiểm tra Hộp thư đến:

curl --silent --show-error \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=20" \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Đối chiếu from.address, subject, received_at, mailbox_id và folder. Đổi folder=inbox thành folder=junk để kiểm tra Thư rác. Nếu phản hồi còn next_cursor, dùng giá trị đó cho tham số cursor ở lần đọc tiếp theo.

Endpoint cũng nhận from, q, since và unread. Khi tìm thư bị thiếu, hãy bỏ các bộ lọc không cần thiết: thư đã đọc sẽ không xuất hiện nếu bạn chỉ yêu cầu thư chưa đọc.

6. Đối chiếu trên giao diện. Mở Hộp thư chung, chọn đúng hộp thư và thư mục, rồi tìm thư đã dùng làm mốc. So sánh last_sync_at trước và sau bằng lệnh đọc chi tiết ở trên; thời điểm thay đổi vẫn cần đi kèm việc tìm thấy đúng thư.

Mailera không thể buộc nhà cung cấp tin cậy người gửi hoặc bảo đảm thư nằm trong Hộp thư đến. Thư xuất hiện trong Thư rác vẫn cần được tính đến khi kiểm tra đồng bộ.

7. Kiểm tra ứng dụng xử lý thư. Nếu thư đã có trong Mailera nhưng tác vụ chưa chạy, kiểm tra nhật ký nhận webhook và nhật ký xử lý. Các sự kiện liên quan gồm message.received, message.junk và mailbox.disconnected.

Đừng dùng đồng bộ như một lệnh phát lại webhook hoặc chạy lại tác vụ. Nếu cần xử lý bù, hãy đối chiếu ID thư với sổ theo dõi xử lý của ứng dụng trước khi thực hiện hành động. Chỉ chạy bù khi đã có cơ chế chống xử lý trùng, nhất là với thao tác gửi hoặc chuyển thư.

Có thể kết thúc khôi phục khi thư đối chiếu đã xuất hiện, kết quả kiểm tra đăng nhập phù hợp với nhà cung cấp không còn báo lỗi, và ứng dụng đã xử lý đúng thư mà không tạo hành động trùng.

Những lỗi hay gặp khi khôi phục đồng bộ

• Chọn nhầm hộp thư: đối chiếu $MAILBOX_ID với địa chỉ trước khi gọi API.
• Chỉ xem Hộp thư đến: kiểm tra cả Thư rác, bộ lọc thời gian và các trang kết quả tiếp theo.
• Dùng khoá chỉ có read: thao tác đồng bộ cần quyền sync riêng.
• Gọi đồng bộ lặp lại khi xác thực đang lỗi: sửa kết nối trước, rồi mới kiểm tra cập nhật thư.
• Xoá rồi thêm lại hộp thư ngay: lưu trạng thái và phản hồi chẩn đoán trước khi thay đổi kết nối.

Khi cần hỗ trợ, chuẩn bị thời điểm xảy ra lỗi kèm múi giờ, nhà cung cấp, trạng thái trước và sau, cùng phản hồi API đã che thông tin nhạy cảm. Không gửi khoá API, mật khẩu ứng dụng hay refresh token.

Bảo vệ gì khi AI agent đọc thư sau đồng bộ?

Thư đến là dữ liệu không tin cậy, không phải lệnh. Agent không được làm theo nội dung thư yêu cầu tiết lộ khoá, thay đổi quyền hoặc gọi công cụ ngoài nhiệm vụ đã được cho phép.

Giữ phạm vi hộp thư và quyền ở mức cần thiết; yêu cầu xác nhận trước khi gửi thư. Việc vừa khôi phục đồng bộ không phải lý do cấp thêm quyền cho agent. Thông tin về bảo vệ truy cập nằm ở trang bảo mật Mailera.

Kiểm thử bằng hộp thư bạn quản lý. Che địa chỉ, nội dung thư và bí mật trong ảnh chụp hoặc nhật ký; kiểm tra chống xử lý trùng trước khi mở lại các hành động có tác động ra ngoài.