I'm building a notification system with retries and delivery logs

Sounds good — a notification system with retries and delivery logs usually benefits from a clear separation between:

1. Notification intent
   What should be sent, to whom, and by which channel.

2. Delivery attempts
   Each try to deliver the notification, including retries.

3. Delivery log / audit trail
   A durable record of every state change and external response.

A solid starting design:

Core entities

notifications

Represents the message to be sent.

• id
• recipient_id
• channel (email, sms, push, etc.)
• template_id
• payload
• status (pending, processing, sent, failed, cancelled)
• created_at
• updated_at

notification_attempts

One row per delivery try.

• id
• notification_id
• attempt നമ്പర్ / attempt_number
• provider
• status (queued, sending, success, retryable_failure, permanent_failure)
• error_code
• error_message
• request_payload
• response_payload
• started_at
• finished_at

notification_logs

Append-only audit log.

• id
• notification_id
• attempt_id nullable
• event_type (created, queued, attempt_started, attempt_succeeded, attempt_failed, retry_scheduled, dead_lettered)
• details JSON
• created_at

Retry strategy

Use a retry policy based on failure type:

• Retryable: network timeouts, provider 5xx, rate limits, temporary SMTP failures
• Non-retryable: invalid recipient, malformed payload, unsubscribed user, hard bounce

Recommended:

• exponential backoff
• jitter
• max attempts
• dead-letter after max attempts

Example:

• attempt 1 immediately
• attempt 2 after 30s
• attempt 3 after 2m
• attempt 4 after 10m
• then fail permanently

Status flow

Typical lifecycle: pending -> queued -> processing -> sent or pending -> queued -> processing -> retry_scheduled -> processing -> failed

Important concerns

• Idempotency: prevent duplicate sends if workers retry or crash.
• Concurrency control: only one worker should process a notification at a time.
• Deduplication: if the same business event triggers multiple notifications, decide whether duplicates are allowed.
• Provider abstraction: keep channel-specific delivery logic behind adapters.
• Observability: store correlation IDs, provider message IDs, latency, and error details.
• Compliance: respect unsubscribe/opt-out, quiet hours, and locale/timezone preferences.

Suggested processing pipeline

1. Create notification record
2. Enqueue job
3. Worker picks up job
4. Create attempt record
5. Call provider
6. Record success/failure
7. If retryable failure, schedule next attempt
8. Append log event at each step

If you want, I can help you with any of these next:

• a database schema
• an event/state machine design
• a retry algorithm
• a code example in your stack
• an API design for creating and querying notifications