Skip to content

Feature Notifications vi

Jump to bottom
SkimMail docs edited this page Sep 15, 2026 · 1 revision

English · Tiếng Việt · 中文

Notifications

Từ 1.3.0, SkimMail có thể báo cho bạn biết khi có chuyện xảy ra mà bạn không phải ngồi nhìn: một tài khoản ngừng sync, một egress chết, một phiên đăng nhập OAuth sắp hết hạn — và từ 1.4.0, bất cứ thứ gì rules của bạn cho là đáng báo. Việc gửi đi qua các notification channel bạn cấu hình một lần và mọi tính năng dùng chung.

Nó giải quyết chuyện gì

Hai bài toán khác nhau, và nên tách chúng ra vì chúng hỏng theo những kiểu khác nhau.

Alert vận hành ("Watchtower") trả lời: server này còn làm việc không? Một trình đọc mail self-host đã âm thầm ngừng sync từ ba tuần trước còn tệ hơn một cái chết hẳn, và chẳng ai ngồi canh một dashboard mà họ không có lý do để mở.

Push notification trả lời: có gì tôi quan tâm vừa tới không? Đó là đối tượng khác — chính bạn, trên điện thoại — và là một đường gửi khác.

Nó nằm ở đâu

  • Settings ▸ Notifications — tuỳ chọn push, các notification channel, và mỗi channel bắn cho những sự kiện Watchtower nào. Đọc thiết lập là mức viewer; đổi thiết lập là operator.
  • Rules định tuyến vào đúng các channel đó: Settings ▸ Rules. Xem Rules & Signals.

Toàn bộ những thiết lập này áp dụng cho cả instance, không theo từng người dùng: mọi người dùng của instance dùng chung một bộ channel và một bộ tuỳ chọn push.

Hai loại thông báo

Alert Watchtower Push
Trả lời câu hỏi server còn chạy không? có thư mới không?
Gửi tới channel (chat, webhook) trình duyệt và thiết bị
Kích hoạt bởi auto-stop, egress chết, OAuth hỏng thư mới, hoặc hành động push của một rule
Quiet hours không áp dụng có áp dụng
Cần có một channel một trình duyệt đã đăng ký hoặc một thiết bị FCM

Alert không bị quiet hours bịt miệng, và đó là chủ ý: quiet hours nói về thư, còn một tài khoản ngừng sync lúc 2 giờ sáng thì 8 giờ sáng vẫn đang ngừng.

Notification channel

Settings ▸ Notifications ▸ Notification channels. Sáu loại:

Loại Bạn cung cấp gì Bí mật được giữ thế nào
Webhook một URL http(s), cộng một secret ký HMAC tuỳ chọn URL để nguyên văn, secret được mã hoá
Telegram một bot token và một chat ID token được mã hoá
Slack một incoming-webhook URL chính URL là credential — được mã hoá
Discord một incoming-webhook URL được mã hoá
Microsoft Teams một URL Workflows (Power Automate) được mã hoá
Google Chat một incoming-webhook URL được mã hoá

Mọi bí mật được lưu đều ghi-một-chiều: API nói có bí mật hay không, chứ không bao giờ nói nó là gì, và để trống ô khi lưu thì giá trị cũ được giữ. Nếu một lỗi gửi tình cờ chứa credential — ví dụ một bot token nằm trong URL — nó bị lược đi trước khi lỗi tới log hay API.

Các channel chat nhận một bản render thuần văn bản, có chủ ý: không markdown và không parse mode, để tên tài khoản hay chuỗi lỗi của nhà cung cấp có chứa ký tự định dạng cũng không thể làm vỡ hay bóp méo thông điệp. Teams nhận một vỏ Adaptive Card vì định dạng connector O365 cũ đã bị khai tử.

Mỗi channel có công tắc enabled riêng, bộ công tắc Alert me when riêng, và một nút Send test gửi một sự kiện giả rồi báo mã trạng thái HTTP cùng thời gian khứ hồi. Hãy lưu channel trước khi test.

Alert Watchtower

Ba sự kiện, mỗi cái bật/tắt độc lập trên từng channel:

Sự kiện Bắn khi Mặc định
account_down cầu dao tự động dừng một tài khoản sau nhiều lần lỗi liên tiếp bật
proxy_down egress mà tài khoản bị dừng đó dùng đã suy ra trạng thái down bật
oauth_expiring lỗi của một tài khoản Gmail/Outlook bị dừng trông giống lỗi xác thực tắt

Cả ba đều là hệ quả của cầu dao auto-stop, nên chúng bắn đúng lúc một tài khoản bị dừng, chứ không phải mỗi lần sync hỏng — xem Sync và Sync Health để biết cái gì kích hoạt nó. Riêng proxy_down còn được khử trùng lặp theo từng egress với cooldown 30 phút, để một proxy chết đang cõng tám tài khoản không sinh ra tám alert.

oauth_expiring mặc định tắt vì nó là tín hiệu mềm hơn: nó được suy ra từ nội dung chuỗi lỗi của nhà cung cấp, và nó luôn đi kèm một account_down cho cùng tài khoản.

Payload webhook và chữ ký

Một channel Webhook nhận một POST JSON:

{
  "event": "account_down",
  "source": "watchtower",
  "message": "me@example.com stopped syncing after 3 failed attempts",
  "account": "me@example.com",
  "account_id": 4,
  "error": "dial tcp: i/o timeout",
  "failures": 3,
  "app": "SkimMail",
  "timestamp": 1757808000
}

source là watchtower với ba sự kiện ở trên và là rule với một rule hit, khi đó event là rule_hit. Với proxy_down thì proxy và proxy_id xuất hiện thay cho các trường tài khoản.

Khi có secret ký, mỗi lần gửi mang theo:

X-SkimMail-Signature: sha256=<hex HMAC-SHA256 of the exact request body>
User-Agent: SkimMail-Watchtower

Việc gửi được thử lại tối đa ba lần — khi lỗi mạng hoặc 5xx, với độ trễ tăng một giây mỗi lần. 4xx là dứt điểm: một payload bị từ chối là vấn đề cấu hình chứ không phải sự cố tạm thời. Mỗi request hết hạn sau 10 giây và cả đợt fan-out sau 20 giây.

Việc gửi đi thẳng từ server, không bao giờ qua egress của một tài khoản. Một webhook trỏ về endpoint của chính bạn; định tuyến nó qua proxy của một hộp thư sẽ vừa bất ngờ vừa để lộ chuyện có alert cho proxy đó. Xem Connections và egress theo từng tài khoản.

Push tới trình duyệt và thiết bị

Hai đường truyền độc lập, dùng một hoặc cả hai:

  • Web Push (từ 1.5.0) — VAPID chuẩn, không cần tài khoản nhà cung cấp nào. Cặp khoá được sinh ra ở lần khởi động đầu tiên và lưu lại, nên không có gì phải cấu hình. Ghi đè bằng VAPID_PUBLIC + VAPID_PRIVATE (cả hai, hoặc không cái nào) và đặt địa chỉ liên hệ bằng VAPID_SUBJECT. Trình duyệt vẫn cần một origin HTTPS và một lần đồng ý trên từng thiết bị, nên một địa chỉ LAN http:// trần không đăng ký được — hãy đặt SkimMail sau TLS hoặc dùng một plugin tunnel.
  • FCM cho di động — tắt trừ khi bạn đặt FIREBASE_ENABLED=true và trỏ FIREBASE_CREDENTIALS tới một file JSON service-account.

Một subscription hoặc device token mà dịch vụ push báo là đã mất sẽ được xoá tự động ở lần gửi kế tiếp, nên các trình duyệt đã thu hồi không tích tụ lại.

Cập nhật thời gian thực bên trong một tab SkimMail đang mở không dùng gì trong số này: chúng tới qua WebSocket mà ứng dụng vốn đang giữ, và đó cũng là đường mà toast in-app của một rule đi tới.

Quiet hours và một thông báo được phép nói gì

Push có một chuỗi kiểm soát và mọi mắt xích đều phải qua:

  1. có một đường truyền (Web Push hoặc FCM);
  2. Enable push notifications đang bật — mặc định nó tắt;
  3. tài khoản nằm trong Active accounts, hoặc danh sách đó rỗng, nghĩa là tất cả;
  4. giờ hiện tại nằm ngoài quiet hours (-1 ở một trong hai đầu là tắt; cửa sổ có thể vắt qua nửa đêm, nên 22 → 7 là một đêm);
  5. thiết lập nội dung quyết định phần chữ.

Thiết lập nội dung, theo thứ tự thắng: Hide content đè lên mọi thứ và cho ra một thông báo chung chung. Nếu không, Show sender và Show subject mỗi cái thêm phần của mình, và tắt cả hai thì bạn cũng nhận một thông báo chung chung.

Hành động push của một rule đi qua đúng chuỗi này, gồm cả quiet hours và thiết lập nội dung — một rule không thể push xuyên qua một khung giờ yên tĩnh. Việc rule gửi tới channel thì khác: nó được định tuyến tường minh theo channel id và không bị lọc bởi các công tắc sự kiện Watchtower của channel đó. Chỉ công tắc enabled của chính channel mới có tác dụng.

Giới hạn
Có từ 1.3.0 (channel 1.4.0, Web Push 1.5.0)
Vai trò viewer để đọc, operator để đổi
Số loại channel 6
Số channel tối đa 50
Số lần thử lại webhook 3 lần; chỉ với 5xx và lỗi mạng
Thời gian chờ 10 giây mỗi lần thử, 20 giây mỗi đợt fan-out
Cooldown proxy_down 30 phút cho mỗi egress
Rule hit mỗi lượt sync 20 mỗi tài khoản, sau đó bị bỏ kèm một dòng log
  • Phạm vi là instance, không phải người dùng. Channel, tuỳ chọn push và quiet hours được chia sẻ cho mọi người đang đăng nhập vào server này.
  • Không có lịch sử gửi. Thất bại được ghi vào log; không có gì xếp hàng một alert hỏng để gửi lại sau.
  • "Only notify for priority mail" được lưu nhưng chưa được dùng. Nó được làm cho phân loại bằng AI, thứ không có trong bản phát hành này, nên hiện không có gì đọc thiết lập đó.

Nó không làm gì

  • Nó không mặc định báo theo từng lá thư. Push tắt cho tới khi bạn bật, và kể cả khi bật thì nó nói "có thư mới", chứ không phải "thư đây".
  • Nó không lưu hay chuyển tiếp thư của bạn. Một channel chat nhận một dòng đã render về một sự kiện; nội dung thư không bao giờ rời server bằng đường này.
  • Nó không thử lại sau một 4xx, và nó không xếp hàng. Một endpoint đang chết lúc alert bắn thì mất alert đó.
  • Nó không báo mỗi lần sync hỏng — chỉ khi cầu dao dừng một tài khoản. Các lỗi thoáng qua hiện trên bảng Sync Health thay vì thành thông báo.
  • Nó không gửi email. SkimMail không có đường gửi thư đi, nên không có tuỳ chọn "email cho tôi khi...".

Xem thêm

SkimMail · skimmail@base101.app · 2026-09-14 · commit 76610cb

Clone this wiki locally