uebliche

Appearance

Feature Plan: Newsletter Dual-Channel Publisher ​

Summary ​

  • Owner: Freddi
  • Status: Discovery
  • Target Release: 2025.11.x
  • Backlog Entry: docs/agendas/uebliche.md → 📥 Inbox (Mailgun worker + Discord bot broadcast)

Goals ​

  • Ensure every newsletter sent from the dashboard reaches both email subscribers and the Discord community within the same publishing window.
  • Provide a structured content payload pipeline so formatting, attachments, and metadata remain consistent across channels.
  • Capture delivery telemetry that verifies Mailgun acceptance and Discord webhook acknowledgements for operational visibility.

Scope ​

  • Provision an asynchronous worker capable of consuming queued newsletter jobs and delivering them via Mailgun with configurable sender identities.
  • Stand up a Discord integration (bot or webhook) that posts newsletter summaries into configured channels with deep links to the full content.
  • Define and persist per-newsletter delivery metadata (channel status, timestamps, external IDs) for audit and retries.
  • Exclude the dashboard composer UI refinements (handled in a separate feature plan).
  • Exclude subscriber management changes beyond the data needed to address channel targets.

Implementation Outline ​

  1. Job Contracts & Storage
    • Define newsletter job schema (content blocks, subject, audience filters, attachments, dedupe token).
    • Persist jobs in existing queue infrastructure or add a dedicated collection/table with status indices.
  2. Worker Runtime
    • Provision a dedicated worker service/module (likely Kotlin coroutine worker) with Mailgun + Discord clients.
    • Load credentials from secrets manager and support per-environment configuration.
  3. Mailgun Delivery Path
    • Build templated email payload generator (HTML + text fallback) with merge vars for personalization.
    • Handle API retries, error logging, and webhook callbacks for bounces/complaints.
  4. Discord Broadcast Path
    • Determine whether to use a lightweight bot user vs. incoming webhook; implement embed formatting and truncation rules.
    • Post summaries with CTA buttons or deep links back to the dashboard/archive.
  5. Dedupe & Idempotency
    • Use newsletter ID + channel key to prevent duplicate sends; persist send receipts for each audience segment.
    • Provide replay tooling for failed deliveries guarded by permissions.
  6. Observability
    • Export metrics/logging for send counts, latency, and failures.
    • Surface status via dashboard admin panel and optional Discord alerts for failures.

Dependencies ​

  • Mailgun account access (API key, domain) and environment-specific sender identities.
  • Discord workspace with permissions to manage webhooks or bot tokens scoped to target channels.
  • Existing job queue infrastructure (tools worker library) or approval to introduce one.
  • Secrets management flow (likely Vault or environment-injected secrets) to store API credentials securely.

Risks & Mitigations ​

  • Mailgun rate limits: Batch sends and throttle per domain; add backoff with jitter to stay within quotas.
  • Discord message formatting constraints: Pre-render content into embed-friendly summaries and cap field sizes; fall back to plain text with link if embed fails validation.
  • Credential sprawl: Centralize secret loading via shared config module and enforce rotation schedule documented with Ops.
  • Operational drift between channels: Implement delivery status reconciliation job that compares Mailgun + Discord receipts and notifies on divergence.

Validation Plan ​

  • Unit/integration tests covering payload generation, dedupe logic, and error handling paths.
  • Stage environment dry-run using a test Discord channel and Mailgun sandbox domain; verify metrics emit correctly.
  • Manual QA checklist for multi-segment newsletters, attachment handling, and replay of failed sends.
  • Post-launch monitoring with automated alerting when failure rate exceeds threshold.

Notes & Decisions ​

  • 2025-11-05 – Opt for Discord webhook first to avoid maintaining bot gateway connection; revisit bot path if reactions/threads become requirements.
  • 2025-11-05 – Mailgun template rendering will reuse existing Handlebars helper library from MOTD system for consistency.

References ​