Notification delivery

Applications need reliable transactional notifications — welcome email, password reset, and future channels — without each service integrating directly with email providers or duplicating template logic.

Forge provides a centralized notification service that accepts send requests, queues work, renders templates, delivers via AWS SES, and tracks outcomes.

This guide is for architecture review, procurement, and product diligence. Detailed ADRs cover templates, rate limiting, and unsubscribe security.

What problem this solves

Without a shared notification layer:

1. Every service talks to SES (or Twilio) directly — duplicated credentials, templates, and retry logic.
2. Callers block on delivery — slow or failing email providers delay user-facing API responses.
3. Bounces and complaints are invisible — reputation and compliance suffer.

Forge follows a fire-and-forget model: callers receive immediate acceptance with a notification ID; delivery happens asynchronously. See ADR-0015.

Architectural overview

  Calling service (e.g. actor-service)
        │
        │  send welcome / password reset
        ▼
  notification-service API
        │
        ├─ Validate actor / template
        ├─ Persist queued notification (PostgreSQL)
        └─ Return 201 + notificationId  ──▶  caller continues
                │
                ▼ (async processing)
        Template render (Qute) → AWS SES send
                │
                ▼
        SNS webhooks (bounce / complaint / delivery)
                │
                ▼
        Update delivery status in database

Callers do not wait for SES delivery. They receive confirmation that the notification was accepted and queued.

Capabilities

Delivery lifecycle and webhooks

In deployed environments, Amazon SES sends delivery, bounce, and complaint events to an SNS HTTPS endpoint on the notification service. The service:

1. Verifies SNS message authenticity (signature validation).
2. Links provider message IDs back to queued notifications.
3. Updates delivery status idempotently.

This gives operators visibility into deliverability without polling provider APIs.

Security and compliance

• Service-to-service auth — Only authorized platform services may trigger notifications; see Service authentication.
• Unsubscribe integrity — Tokens are short-lived and single-use where applicable; see ADR-0019.
• Audit trail — Send actions can emit audit events; see Audit logging.
• Operator responsibilities — SES domain verification, DKIM/SPF, bounce handling policies, and marketing consent rules remain with the deploying organization.

Operator expectations

Further reading

• ADR-0015: Fire-and-forget pattern
• ADR-0016: Provider rate limiting
• Amazon SES best practices — AWS Documentation