Câu hỏi thường gặp (FAQ) — Mailbox

Cài đặt và cấu hình

Cần cấu hình gì trước khi thêm tài khoản email?

Tuỳ theo nhà cung cấp:

Google (Gmail):

• Tạo project trên Google Cloud Console
• Bật Gmail API
• Tạo OAuth2 Client ID (Web Application)
• Cấu hình Redirect URI trỏ về Digiforce server

Microsoft (Outlook):

• Đăng ký ứng dụng trên Azure Portal (App Registration)
• Cấu hình Microsoft Graph API permissions (Mail.Read, Mail.Send, v.v.)
• Cấu hình Redirect URI

Plugin hỗ trợ IMAP/SMTP trực tiếp không?

Plugin chủ yếu sử dụng OAuth2 API của Google (Gmail API) và Microsoft (Graph API) để gửi/nhận email. Điều này an toàn hơn so với IMAP/SMTP truyền thống vì không cần lưu mật khẩu.

Có thể kết nối nhiều tài khoản email không?

Có. Mỗi người dùng Digiforce có thể kết nối nhiều tài khoản email (cả Gmail và Outlook). Mỗi tài khoản được lưu riêng trong bảng mailAccounts với userId tương ứng.

Sử dụng

Email đồng bộ chậm — làm sao khắc phục?

Kiểm tra các yếu tố sau:

1. Tần suất đồng bộ: Vào Settings → Mailbox → General Settings để giảm khoảng thời gian giữa các lần sync
2. Đồng bộ thủ công: Nhấn nút Sync hoặc gọi API mail:messagesSync để trigger sync ngay lập tức
3. Token hết hạn: Nếu OAuth2 token hết hạn và refresh thất bại, plugin không thể đồng bộ. Kiểm tra log và kết nối lại tài khoản nếu cần
4. Giới hạn API: Google và Microsoft có rate limit — nếu gửi quá nhiều request, API có thể bị throttle

Làm sao gửi email hẹn giờ?

Khi soạn email, chọn thời gian gửi tại trường Schedule Send At. Email sẽ được lưu với boxType: scheduled và scheduleSendAt chứa thời điểm gửi. Schedule job của plugin sẽ tự động gửi email khi đến giờ.

Để huỷ email hẹn giờ, sử dụng action mailMessages:cancelTimelySend.

Gửi email hàng loạt hoạt động như thế nào?

1. Tạo mass send campaign trong giao diện
2. Chọn Collection chứa danh sách liên hệ và trường email
3. Plugin lấy danh sách email từ Collection theo filter đã chọn
4. Gửi email tuần tự (hoặc theo batch) qua nhà cung cấp email
5. Theo dõi trạng thái gửi (thành công/thất bại) trong Mass Send Tracking

Có thể sử dụng email template không?

Có. Plugin hỗ trợ bảng mailTemplates để lưu template email có thể tái sử dụng. Khi soạn email, chọn template từ danh sách để điền nội dung tự động.

Lỗi thường gặp

Không nhận được email sau khi kết nối tài khoản?

Kiểm tra theo thứ tự:

1. Tài khoản đã kết nối thành công chưa? Kiểm tra danh sách tài khoản trong Settings
2. Token còn hiệu lực? Nếu token hết hạn, cần kết nối lại
3. Schedule đang chạy? Plugin chạy schedule sau event afterLoad — đảm bảo server đã khởi động hoàn chỉnh
4. Kiểm tra log: Plugin ghi log vào thư mục mailbox/ — xem file log để tìm lỗi cụ thể

Lỗi "Failed to push unread count for user"?

Plugin cố gắng gửi số email chưa đọc đến người dùng qua WebSocket (ws:sendToUser). Lỗi này có thể do:

• Người dùng không online (WebSocket không kết nối) — đây không phải lỗi nghiêm trọng
• Database query thất bại — kiểm tra kết nối database

Email đã gửi nhưng không thấy trong "Đã gửi"?

Email gửi đi được lưu với boxType: out. Kiểm tra:

• Bộ lọc hộp thư đang hiển thị "Đã gửi" (Outbox)
• Email gửi hẹn giờ sẽ nằm trong boxType: scheduled cho đến khi được gửi thực tế
• Email gửi hàng loạt nằm trong boxType: mass

Attachment quá lớn không gửi được?

Giới hạn kích thước attachment phụ thuộc vào nhà cung cấp email:

Nhà cung cấp	Giới hạn
Gmail	25MB mỗi email
Outlook	25MB (có thể cao hơn với OneDrive)

Ngoài ra, cần kiểm tra cấu hình maxFileSize của Digiforce server.

Bảo mật

Dữ liệu email được lưu ở đâu?

• Nội dung email (subject, body, from/to) lưu trong bảng mailMessages trên database Digiforce
• Attachment lưu trong file storage của Digiforce
• Token OAuth2 lưu trong bảng mailAccounts (dạng JSON)

Plugin có quyền truy cập gì trên email?

Plugin yêu cầu quyền:

• Đọc email (Gmail: gmail.readonly, Graph: Mail.Read)
• Gửi email (Gmail: gmail.send, Graph: Mail.Send)
• Quản lý label/folder (tuỳ nhà cung cấp)

Tất cả API endpoint yêu cầu người dùng đã đăng nhập (loggedIn). Mỗi người dùng chỉ truy cập được email của tài khoản mình.