notification-service
Internal backend-to-backend notification microservice for sending email notifications with queue-based processing and retries.
Built for reliability
Everything you need to send notifications at scale — with confidence.
Queue-based Processing
Async delivery via RabbitMQ decouples your API from email sending for maximum throughput.
Automatic Retries + DLQ
Exponential backoff retries with Dead Letter Queue routing ensure no notification is lost.
Delivery Tracking
Full lifecycle tracking in PostgreSQL: queued → sending → sent, with status check endpoints.
Webhook Callbacks
Receive HTTP callbacks for delivery status updates in your calling services.
Health & Readiness
Liveness and readiness endpoints for Kubernetes and Docker health checks.
API Key Auth + Rate Limiting
Optional per-service API key authentication and Redis-based rate limiting.
How it works
A simple, reliable pipeline from request to inbox.
Backend Services
Auth · Order · User
Notification API
Express.js + Validation
RabbitMQ
Queue · Retry · DLQ
Worker
Email processing
SMTP Provider
Gmail · SendGrid · SES
Get started in minutes
Two paths to running notification-service locally.
Use the CLI tool
Interactive wizard to generate .env, docker-compose.yml, and verify your setup.
npx notification-service initOr clone manually
Clone the repo, install dependencies, and configure your .env file.
git clone https://github.com/khodakivskyi/notification-service.git && cd notification-serviceStart dependencies
Spin up PostgreSQL and RabbitMQ with Docker Compose.
docker-compose up -dRun the service
Start the API server and worker processes. Database migrations run automatically.
npm run dev && npm run dev:workersSend your first notification
The API queues the notification and returns an ID. Workers deliver it asynchronously.
curl -X POST http://localhost:3001/api/notifications/send \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","subject":"Hello","htmlContent":"<h1>It works!</h1>"}'