Kết nối email (IMAP/SMTP)

TLDR

Connection giữ thông tin đăng nhập IMAP/SMTP (hoặc OAuth, forward, Twilio) mà một hay nhiều inbox dùng chung. Mật khẩu được mã hoá khi lưu (AES-256-GCM) và luôn hiện *** khi đọc lại. Connection được tạo trong wizard “Connect channel” (/helpdesk/inboxes/new) chứ không có form tạo riêng — chỉ sửa connection đã có mới có màn hình riêng ở Settings → Connections.

Provider nào dùng thật, provider nào là demo

IMAP / SMTP — thật

provider: imap_smtp. Test connection thật sự mở kết nối IMAP (ImapFlow) và liệt kê folder thật. Đây là con đường chính để nhận email vào Helpdesk (inbound_provider: imap).

Forward / Twilio WhatsApp — lưu cấu hình

forward chỉ lưu 1 địa chỉ forward; twilio_whatsapp lưu Account SID

• số điện thoại. Không có bước test riêng trong UI.

OAuth — Gmail / Outlook / Custom

provider: gmail | outlook | custom_oauth. Mô hình “bring your own app”: admin nhập client ID/secret + endpoint của OAuth app ngay trong wizard (Gmail/Outlook có sẵn preset, Custom nhập tay). Mailbox được poll qua IMAP XOAUTH2 — dùng chung pipeline inbound. Thêm bao nhiêu connection cũng được, mỗi cái một app riêng.

Kết nối mailbox bằng OAuth (bring your own app)

Đây là cách thêm một hộp thư (Gmail, Outlook/365, hay bất kỳ provider OAuth2 + IMAP nào) làm nguồn inbound mà không lưu mật khẩu — dùng OAuth chính chủ của provider. Client ID/secret + endpoint lưu trên chính connection (mã hoá at rest), không phải biến môi trường — nên một admin có thể thêm nhiều mailbox, mỗi cái backing bởi một OAuth app khác nhau.

Vẫn phải đăng ký OAuth app bên provider một lần

Chuẩn OAuth bắt buộc phải có một app đã đăng ký (client ID/secret) và redirect URI được whitelist sẵn. Wizard sẽ hiển thị đúng redirect URI cần dán vào app — đây là bước duy nhất không thể tự động hoá.

Thiết lập OAuth app (ví dụ Google — một lần cho mỗi app):

1. Vào Google Cloud Console → tạo/chọn project → APIs & Services → OAuth consent screen: thêm scope https://mail.google.com/, thêm tài khoản Gmail cần kết nối vào Test users (nếu app chưa verify).

2. Credentials → Create credentials → OAuth client ID → loại Web application. Ở Authorized redirect URIs, dán đúng URI mà wizard hiển thị:

   • Dev: http://localhost:8888/api/helpdesk/oauth/callback
   • Prod: https://<admin-domain>/api/helpdesk/oauth/callback

3. Bật IMAP trong hộp Gmail (Gmail → Settings → Forwarding and POP/IMAP → Enable IMAP).

4. (Tuỳ chọn, chỉ khi prod) đặt redirect URI chuẩn cho backend — mặc định dev đã đúng:

   backend/.env

   HELPDESK_OAUTH_REDIRECT_URI=https://<admin-domain>/api/helpdesk/oauth/callback

   Không cần set client ID/secret ở env nữa — chúng nhập trong wizard.

Kết nối (agent/admin):

1. Wizard New inbox → Connect a new channel → chọn Gmail, Outlook, hoặc Custom OAuth (IMAP).

2. Form OAuth hiện ra với redirect URI cần whitelist (copy vào app ở bước trên) + các field: tên connection, địa chỉ mailbox, Client ID, Client secret. Gmail/Outlook đã điền sẵn authorize/token URL + scope + IMAP host; Custom thì mở Edit endpoints / scopes để nhập tay. Riêng Outlook có thêm ô Tenant (xem note dưới).

3. Bấm Connect & authorize → chuyển sang trang đồng ý của provider → đồng ý quyền → quay về Settings → Connections với connection đã connected.

4. Tạo inbox trên connection vừa kết nối (nhánh existing connection của cùng wizard này).

Ghi chú

Access token + refresh token + client secret đều mã hoá khi lưu và hiện *** khi đọc lại. Access token tự refresh khi hết hạn (dùng creds của chính connection). Nếu thu hồi quyền bên provider, connection bị đánh dấu needs_reauth và ngừng poll tới khi kết nối lại. Chi tiết kỹ thuật: Inbound pipeline.

Riêng Microsoft / Outlook — chọn Tenant

Endpoint Microsoft có một segment tenant. Form Outlook có ô Tenant / Directory (mặc định organizations):

• organizations — mọi tài khoản work/school (Azure AD). Khuyến nghị cho IMAP.
• common — work/school + cá nhân (personal outlook.com hầu như không dùng được IMAP XOAUTH2 bên thứ ba).
• consumers — chỉ tài khoản cá nhân.
• Directory (tenant) ID hoặc domain (vd contoso.onmicrosoft.com) — bắt buộc nếu app Azure đăng ký dạng single-tenant.

Giá trị này phải khớp với “Supported account types” chọn khi tạo app trên Azure — lệch → login lỗi AADSTS50194 / AADSTS700016. Đổi tenant trong ô này thì authorize/token URL tự dựng lại, không cần sửa tay. App cần API permission IMAP.AccessAsUser.All (delegated). Cơ chế: OAuth: đăng nhập & data.

Tạo connection mới (qua wizard)

Không có nút “Tạo connection” độc lập — connection luôn được tạo trong lúc tạo inbox đầu tiên dùng nó.

1. Vào Settings → Connections → bấm Connect channel (hoặc bắt đầu trực tiếp từ New inbox).

2. Chọn Channel (Email/WhatsApp) → chọn Provider. Với Email, chọn IMAP/SMTP.

3. Nhập thông tin IMAP (incoming): Host, Port, Username, Password, SSL/TLS. Nhập SMTP (outgoing): có thể tick “Use the same credentials as IMAP” để dùng chung tài khoản, hoặc nhập riêng Host/Port/Username/Password/STARTTLS.

4. Bấm Test connection. Bước này chỉ kiểm tra IMAP thật (kết nối + liệt kê folder) — SMTP không được test ở bước này, chỉ được lưu kèm theo. Test thành công mới cho phép Continue.

5. Tiếp tục các bước tạo inbox (routing/folder, đặt tên) — xem chi tiết ở Tạo inbox & định tuyến. Khi bấm Create inbox ở bước cuối, connection và mật khẩu IMAP/SMTP vừa nhập được lưu (mã hoá) cùng lúc.

Ghi chú

Vì bước “Create inbox” lưu connection ngay, mật khẩu nhập ở wizard tạo mới đã được lưu — không cần thao tác Save nào thêm.

Sửa connection đã có

1. Settings → Connections → bấm biểu tượng bút chì trên connection cần sửa.

2. Với provider IMAP/SMTP, slideover hiện 2 khối Incoming (IMAP) và Outgoing (SMTP). Trường Password luôn để trống khi mở (không hiện lại mật khẩu cũ) kèm ghi chú “Leave blank to keep the current password.”

3. Có thể bấm Test IMAP ngay trong màn hình sửa để kiểm tra thông tin vừa gõ.

4. Bấm Save để lưu.

Test không tự lưu mật khẩu

Ở màn hình sửa connection, nút Test IMAP chỉ dùng để kiểm tra kết nối — nó không ghi mật khẩu xuống database. Nếu bạn gõ mật khẩu mới, bấm Test thấy “Connected” rồi đóng slideover mà không bấm Save, mật khẩu mới sẽ không được lưu, và IMAP sẽ tiếp tục dùng mật khẩu cũ (hoặc rỗng) khi poll nền — dẫn tới lỗi âm thầm không có ticket mới. Luôn bấm Save sau khi Test thành công. Chỉ có nút Test IMAP; không có nút Test SMTP riêng ở màn hình connection (SMTP của connection chỉ được xác minh gián tiếp qua Outbound tab của inbox — xem bên dưới).

Mask & mã hoá mật khẩu

Mask khi đọc

Các trường nhạy cảm (imap_password, smtp_password, oauth_token, oauth_refresh_token, twilio_auth_token, webhook_secret) luôn trả về *** nếu đã có giá trị, hoặc null nếu chưa từng đặt — không bao giờ lộ giá trị thật qua API.

Mã hoá khi ghi

Trước khi ghi xuống DB, các trường trên được mã hoá AES-256-GCM bằng khoá suy ra từ secret của ODP. Chỉ backend Helpdesk giải mã được (lúc IMAP connect / gửi SMTP).

Test SMTP nằm ở đâu?

SMTP thực sự chỉ được test tại tab Outbound của từng inbox (không phải ở màn hình Connection), vì mỗi inbox có thể dùng SMTP dùng chung (Shared — theo connection) hoặc SMTP riêng (Custom). Nút Test SMTP chỉ hiện khi chọn mode Custom. Xem chi tiết mục outbound override ở Tạo inbox & định tuyến.

Danh sách folder (available_folders)

Danh sách folder IMAP hiển thị ở tab Folder của inbox không phải nhập tay — nó được lưu tự động mỗi lần Test IMAP thành công (test = tiện thể fetch danh sách folder). Nếu đổi mật khẩu hộp thư ngoài đời và cần cập nhật lại danh sách folder, chạy lại Test IMAP để làm mới.

Đọc tiếp

• Tạo inbox & định tuyến — dùng connection vừa tạo để lập inbox
• Xử lý sự cố thường gặp — email không thành ticket, không gửi được reply