Giao diện
Cài đặt và sử dụng — Mailbox
Tổng quan
Plugin Mailbox cho phép nhận, gửi, và quản lý email trực tiếp trong Digiforce — kết nối với tài khoản email doanh nghiệp (Gmail, Outlook) thông qua OAuth2. Email được tổ chức theo conversation thread, hỗ trợ reply/forward, đính kèm file, gửi hàng loạt, và hẹn giờ gửi.
Bước 1: Kích hoạt Plugin
Truy cập Settings → Plugin Manager, tìm plugin-mailbox và bật plugin. Khởi động lại server.
Bước 2: Cấu hình tài khoản email
Vào Settings → Mailbox để thêm tài khoản email. Plugin hỗ trợ hai nhà cung cấp chính:
Google (Gmail)
- Nhấn Add Account → Google
- Plugin tạo link OAuth2 (
oauth2url) và chuyển hướng đến trang xác thực Google - Sau khi cấp quyền, plugin nhận authorization code và tạo tài khoản (
createAccount) - Token được lưu trong bảng
mailAccounts
Microsoft (Outlook/Office 365)
- Nhấn Add Account → Microsoft
- Luồng tương tự qua Microsoft OAuth2 (MSAL)
- Sử dụng Microsoft Graph API để gửi/nhận email
Bảng cấu hình tài khoản
| Trường | Kiểu dữ liệu | Mô tả |
|---|---|---|
type | string | Loại nhà cung cấp: google hoặc microsoft |
email | string | Địa chỉ email |
userId | bigInt | ID người dùng Digiforce sở hữu tài khoản |
tokens | json | Token OAuth2 (access token, refresh token) |
settingId | bigInt | Liên kết đến cấu hình mail setting |
config | json | Cấu hình bổ sung (signature, v.v.) |
Bước 3: Đồng bộ email
Sau khi thêm tài khoản, plugin tự động bắt đầu đồng bộ email:
- Đồng bộ định kỳ: Plugin chạy schedule tự động đồng bộ email mới
- Đồng bộ thủ công: Nhấn Sync trong giao diện hoặc gọi API
mail:messagesSync - Đồng bộ lại toàn bộ: Gọi
mail:messagesResyncđể sync lại từ đầu
Tính năng chính
Gửi email
Soạn email mới hoặc reply/forward từ giao diện Digiforce:
| Tính năng | Mô tả |
|---|---|
| Soạn mới | Rich text editor, hỗ trợ To/Cc/Bcc |
| Reply / Forward | Trả lời hoặc chuyển tiếp trong conversation thread |
| Đính kèm file | Upload attachment qua mail:messageAttachmentUpload |
| Hẹn giờ gửi | Đặt scheduleSendAt — email sẽ được gửi tự động vào thời điểm đã chọn |
| Lưu nháp | Lưu bản nháp qua mail:messageSavingDraft |
| Chữ ký | Chọn signature cho mỗi tài khoản email |
Gửi hàng loạt (Mass Send)
Plugin hỗ trợ gửi email hàng loạt đến danh sách liên hệ từ Collection:
mailMassMessages:send— Gửi hàng loạtmailMassMessages:resend— Gửi lại email thất bạimailMassMessages:cancel— Huỷ gửi hàng loạt- Theo dõi trạng thái gửi qua Mass Send Tracking
Quản lý email
| Tính năng | API | Mô tả |
|---|---|---|
| Đánh dấu đã đọc | mail:messageSetReaded | Cập nhật trạng thái isRead |
| Chuyển thùng rác | mailMessages:trash | Chuyển email sang boxType: trash |
| Xoá vĩnh viễn | mailMessages:destroy | Xoá email khỏi database |
| Huỷ gửi hẹn giờ | mailMessages:cancelTimelySend | Huỷ email đã hẹn giờ |
| Gán nhãn | Label association | Gán label (nhiều-nhiều) cho email |
| Ghi chú | Note association | Thêm ghi chú nội bộ cho email |
| Đánh dấu Todo | isTodo flag | Đánh dấu email cần theo dõi |
Hộp thư (Box Types)
| Loại | Giá trị | Mô tả |
|---|---|---|
| Hộp thư đến | in | Email nhận được |
| Đã gửi | out | Email đã gửi |
| Nháp | draft | Bản nháp chưa gửi |
| Thùng rác | trash | Email đã xoá (có thể khôi phục) |
| Spam | spam | Email rác |
| Lưu trữ | archive | Email đã lưu trữ |
| Hẹn giờ | scheduled | Email chờ gửi theo lịch |
| Hàng loạt | mass | Email gửi hàng loạt |
Cấu hình chung (General Settings)
Vào Settings → Mailbox → General Settings để cấu hình:
- Tần suất đồng bộ email
- Khi thay đổi cấu hình, schedule tự động cập nhật (event
mailGeneralSettings.afterSave)
Database Schema
| Bảng | Mô tả |
|---|---|
mailAccounts | Tài khoản email (type, email, tokens, config) |
mailMessages | Email messages (from, to, subject, body, boxType, attachments) |
mailMessageLabels | Nhãn email (label, color) |
mailLabelRel | Bảng trung gian: nhiều-nhiều giữa message và label |
mailMessageNotes | Ghi chú nội bộ cho email |
mailTemplates | Template email có thể tái sử dụng |
mailMassMessages | Quản lý gửi email hàng loạt |
mailSettings | Cấu hình IMAP/SMTP cho từng tài khoản |
mailGeneralSettings | Cấu hình chung (tần suất sync, v.v.) |
Lưu ý khi triển khai
- OAuth2 credentials: Cần cấu hình Google OAuth Client ID hoặc Microsoft App Registration trước khi thêm tài khoản
- Token refresh: Plugin tự động refresh token khi hết hạn
- Email lowercase: Plugin tự động normalize địa chỉ email về lowercase (hook
registerMailAddressLowercaseHook) - Path traversal: Attachment upload được bảo vệ chống path traversal
- Database index: Plugin tự động tạo index cho các trường thường dùng trong filter (
boxType,userId,email,isRead, v.v.) - Dung lượng: Email có attachment lớn sẽ tăng dung lượng database — cân nhắc cấu hình giới hạn kích thước