Notifications and Deep Links

Herald notifications are local-first mailbox nudges. On macOS they use the system notification center when launched from a macOS app bundle and can activate a running Herald TUI through herald://mail/... deep links; raw CLI, tmux, and SSH sessions no-op cleanly instead of requesting Notification Center access. On other platforms Herald either uses delivery-only support or no-ops cleanly.

Event Defaults

New mail and sync failures are enabled by default. Completion notifications for delete/archive batches, classification runs, and chat results exist as opt-in events because those can become noisy during regular inbox work.

Deep-Link Contexts

Herald supports folder, message, sender, search, and compose links:

herald://mail/folder?folder=INBOX
herald://mail/message?folder=INBOX&message_id=<message-id>
herald://mail/sender?folder=INBOX&sender=alerts%40example.com
herald://mail/search?folder=INBOX&q=invoice
herald://mail/compose?to=a%40b.com&subject=Hello

Use --open for deterministic testing:

herald --demo --open 'herald://mail/search?folder=INBOX&q=invoice'

macOS Permissions

The first native macOS notification from an app-bundle launch may ask for Notification Center permission. Raw CLI, tmux, and SSH launches do not request macOS notification permission.

Other Platforms

Linux preserves delivery-only behavior through notify-send when available. Unsupported platforms keep the app behavior unchanged and do not advertise click-through activation.