Background Workers

Worker Manager#

The API server runs a worker manager that schedules 7 periodic jobs. Every job runs once immediately at startup, before its ticker begins, so a fresh boot does not wait a full interval for the first pass. A job configured with a zero or negative interval is logged as an error and skipped entirely. Each run is wrapped in panic recovery, so a panicking job logs and continues on the next tick rather than taking the process down. Each runs at its interval (most configurable, two fixed) and is gracefully stopped on shutdown.

Jobs#

Cleanup

Interval: workers.cleanup_interval (default: 5m)

Emits inbox.expired (webhook, audit entry, and realtime notification) for each lapsed inbox, then removes expired inboxes and their emails/attachments (including stored objects), expired sessions, expired password-reset tokens, and expired API keys.

DNS Recheck

Interval: workers.dns_recheck_interval (default: 1h)

Re-verifies MX, TXT and SPF records for every domain, in pages of 100. A lookup error preserves the previous status rather than downgrading it, and any change is written to domain_verification_history with trigger_source = "background".

Webhook Retry

Interval: workers.webhook_retry_interval (default: 1m)

Clears the failure_count bookkeeping field on active webhooks sitting at 1 or 2 failures. It re-sends nothing — replaying a stored payload would deliver a stale event to the consumer. Per-delivery retries are applied inline by the dispatcher: 3 attempts, waiting 0s, then 5s, then 25s.

Reconciler

Interval: workers.reconciler_interval (default: 1m)

Synchronizes Redis inbox routing cache with PostgreSQL. Ensures active inboxes have corresponding Redis entries and expired inboxes are removed.

Analytics

Interval: workers.analytics_interval (default: 5m)

Recomputes the platform-wide system-stats snapshot and caches it in Redis under bb:analytics:system_stats with a configurable TTL (defaults.analytics_cache_ttl, default: 2h). Per-org and per-team aggregates are maintained incrementally by the realtime bridge in the daily_*_stats tables.

Invite Expiry

Interval: 24h (fixed)

Emails each inviter a reminder about their invitations expiring within the next 24 hours, then deletes invitations that have already lapsed.

Admin Stats

Interval: 10s (fixed)

Pushes live platform counts (emails, inboxes, domains, users, teams, storage) to the admin-stats WebSocket hub for the system-admin dashboard.

Configuration#

workers:  dns_recheck_interval: 1h  cleanup_interval: 5m  webhook_retry_interval: 1m  reconciler_interval: 1m  analytics_interval: 5m  # invite_expiry (24h) and admin_stats (10s) run at fixed, non-configurable intervals

The admin_stats job short-circuits when no admin client is connected — it skips the stats query rather than computing a snapshot nobody will receive.

Every API process starts all seven workers. There is no leader election and no flag to run an API instance without them, so a second replica duplicates every job — see Production Deployment.