Notification Service

Cloud-agnostic email and SMS delivery with built-in idempotency, provider abstraction, and a complete audit trail for every message sent.

Why It Matters

Agent bundles, bots, and platform services all need to send notifications: password resets, alert emails, SMS verifications, workflow status updates. Without a centralized service, notification code ends up scattered across every consumer — each one integrating directly with a cloud provider, duplicating credentials, retry logic, and configuration.

The result is provider lock-in, missing audit trails, and the ever-present risk of duplicate sends. The Notification Service solves all of this with a single REST API that abstracts over providers, enforces idempotency at the database level, and logs every send with full traceability.

Key Capabilities

• Multi-Channel Delivery: Email and SMS today, push notifications coming in Phase 2
• Provider Abstraction: Pluggable adapter architecture — swap providers without changing application code
• Idempotency: Client-provided keys with database-level dedup, race-safe via INSERT ON CONFLICT
• Credential Safety: Secrets never stored in database, resolved from environment variables at runtime
• Audit Trail: Immutable log of every send with correlation IDs, status tracking, and provider message IDs
• Admin API: Manage provider configurations, activate/deactivate channels, validate credentials

How It Works

A consumer sends a REST request to the Notification API with an idempotency key. The service resolves the active provider for the requested channel and performs a deduplication check. If the key is new, the request is translated and dispatched through the configured provider. The consumer receives a response with the notification ID, send status, and provider message ID. If the idempotency key already exists, the existing result is returned without sending again.

Send an Email

Send a notification by posting to the channel endpoint with an idempotency key. The service handles provider selection, deduplication, and audit logging automatically.

{
  "idempotencyKey": "welcome-email-user-12345",
  "to": ["alice@example.com"],
  "subject": "Welcome to the platform",
  "html": "<h1>Welcome!</h1><p>Your account is ready.</p>",
  "metadata": { "templateId": "onboarding", "userId": "12345" }
}

Response Format

Every send request returns a SendResult containing the internal notification ID, the provider-assigned message ID for reconciliation, the current status, channel, and a timestamp. New notifications return 202 Accepted; duplicate idempotency keys return 200 OK with the existing result.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "providerMessageId": "provider-assigned-id",
  "status": "sent",
  "channel": "email",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Provider Architecture

The Notification Service uses a pluggable adapter architecture. Each provider adapter implements a standard channel interface, translating the normalized notification request into the provider's format and mapping the response back to a consistent SendResult. Adding a new provider requires no changes to the REST API, database schema, or existing consumers.

Consumers never specify which provider to use — they just say "send an email" and the service routes to whatever provider is active for that channel. When you activate a new provider, the service atomically deactivates the previous one.

What It's Not

The Notification Service is purpose-built for transactional and workflow-driven message delivery. It is intentionally scoped:

• Not a marketing email platform — No campaigns, A/B testing, or unsubscribe management
• Not a real-time messaging system — No WebSocket chat, presence, or typing indicators
• Not a template engine — Consumers send pre-rendered content; templates may come in a future phase

Use Cases