📧 Mailer - Production-Grade Bulk Email Service

✨ Core Features

▼

🚀 High Deliverability - SPF, DKIM, DMARC

📦 Queue-Based Processing - BullMQ + Redis

📧 Email Suppression - Auto bounce/complaint handling

🔄 Retry Logic - Exponential backoff

💀 Dead Letter Queue - Auto DLQ for failed jobs

🔐 API Authentication - Secure API key management

✅ Request Validation - Zod schema validation

❤️ Health Checks - Liveness & readiness endpoints

📝 Structured Logging - Pino logger with pretty printing

📊 Comprehensive Metrics - Built-in metrics tracking

🛑 Graceful Shutdown - Clean worker/server termination

🐳 Docker Ready - Production-grade multi-stage build

🛠️ Technology Stack

▼

Node.js 20+

TypeScript

Fastify

PostgreSQL 15+

Redis 7+

BullMQ

Prisma ORM

AWS SES

Docker

Node v24.11.1 ✓
npm v11.6.2 ✓
TypeScript v5.6.0 ✓
Fastify v4.0.0 ✓
PostgreSQL 15 (ready)
Redis 7 (ready)

⚡ 5-Minute Quick Start

▼

# 1. Install dependencies
npm install

# 2. Generate Prisma client
npm run prisma:generate

# 3. Configure environment  
cp .env.example .env
# Edit .env with your settings

# 4. Setup database
npm run prisma:push
npm run seed

# 5. Generate API key
npm run gen-key "My Key"

# 6. Start development (open 2 terminals)
npm run dev:api      # Terminal 1: API Server
npm run dev:worker   # Terminal 2: Email Worker

🔌 API Endpoints

▼

Health & Status

GET /api/v1/health       # Liveness check (no auth)
GET /api/v1/ready        # Readiness check (no auth)
GET /api/v1/metrics      # Metrics dashboard (no auth)

Admin Management (requires Bearer token)

GET    /api/v1/admin/keys            # List API keys
POST   /api/v1/admin/keys            # Create new key
DELETE /api/v1/admin/keys/:id        # Delete key
GET    /api/v1/admin/suppression     # View suppressed emails

Templates (requires Bearer token)

GET    /api/v1/templates            # List templates
POST   /api/v1/templates            # Create template
PUT    /api/v1/templates/:id        # Update template
DELETE /api/v1/templates/:id        # Delete template

Batch Sending (requires Bearer token)

POST   /api/v1/batches              # Send email batch
GET    /api/v1/batches/:id          # Get batch status
DELETE /api/v1/batches/:id          # Cancel batch

Authentication

Authorization: Bearer YOUR_API_KEY

# Example:
curl -H "Authorization: Bearer sk_test_abc123..." \\
     http://localhost:3000/api/v1/admin/keys

🏗️ Architecture

▼

System Components

API Server
Fastify-based REST API with Zod validation

Email Worker
BullMQ worker processes email queue

Database
PostgreSQL with Prisma ORM

Message Queue
Redis with BullMQ for job processing

Email Provider
AWS SES for high deliverability

Webhooks
SES bounce/complaint notifications

Data Flow

Client sends POST /api/v1/batches with email list
API validates request with Zod schemas
Emails stored in database (Batch, Recipient records)
Worker pulls batch from Redis queue
Worker sends each email via AWS SES
Results tracked in Event & Metric records
SES webhooks notify of bounce/complaint
Suppression rules auto-apply

🔐 Security Fixes Applied

▼

🔴 CRITICAL Fixes (3)

Unauthenticated Admin Routes
✅ Added Bearer token auth to all admin endpoints

No Rate Limiting
✅ Implemented rate limit middleware (100 req/15min)

Unverified Webhooks
✅ Added SES signature verification

🟠 HIGH Priority Fixes (4)

Database Not Gracefully Closed
✅ Added SIGINT/SIGTERM handlers

Worker Cleanup Missing
✅ Proper disconnect sequence on shutdown

Missing Cascade Deletes
✅ Added cascade delete relationships in Prisma

Poor Email Validation
✅ RFC 5321 compliance with length checks

⚠️ MEDIUM Priority Improvements (4)

No Request Timeout
✅ Set 30-second request timeout

Missing Database Indexes
✅ Added indexes on query fields

Non-Portable SQL
✅ Fixed health check for database portability

Subject Not Compiled
✅ Template subjects now rendered with Handlebars

🚀 Deployment Options

▼

Option A: Docker Compose (Recommended)

docker-compose up

# Services started:
# - PostgreSQL (port 5432)
# - Redis (port 6379)  
# - API Server (port 3000)
# - Email Worker (background)

Option B: Local Development

# Terminal 1: Start API
npm run dev:api

# Terminal 2: Start Worker
npm run dev:worker

# Terminal 3: Start Redis
redis-server

# Terminal 4: Start PostgreSQL
# (ensure service is running)

Pre-Deployment Checklist

✓ npm run build                    # TypeScript compiles
✓ npm run prisma:push             # Database ready
✓ npm run seed                     # Test data loaded
✓ npm run gen-key "Prod Key"      # API key created
✓ curl http://localhost:3000/api/v1/health  # API responds
✓ Environment variables configured
✓ AWS SES verified & credentials set
✓ Database backups in place
✓ Redis persistence configured

📚 Full Documentation

▼

Getting Started

📖 README.md - Project overview ⚡ QUICK_REFERENCE.md - 2-min summary 🔧 QUICKSTART.sh - Setup script

Deployment

🚀 PRODUCTION_DEPLOYMENT.md ✅ PRODUCTION_CHECKLIST.md 🐳 Dockerfile - Container setup

Technical Docs

🏗️ ARCHITECTURE.md - System design 🔌 API_EXAMPLES.md - API reference 📋 PRODUCTION_FEATURES.md - Features

Reference

🔍 ISSUES_FIXED_REPORT.md - All fixes 📝 PRODUCTION_FIXES.md - Details 🆘 TROUBLESHOOTING.md - Common issues

💡 All files are .md format - open with any text editor in VS Code

📁 Project Structure

▼

mailer/
├── src/
│   ├── api/                    # REST API (Fastify)
│   │   ├── index.ts           # Entry point
│   │   ├── server.ts          # Server setup
│   │   └── routes/            # API endpoints
│   │       ├── health.ts      # Health checks
│   │       ├── admin.ts       # Admin endpoints
│   │       ├── batches.ts     # Email batches
│   │       ├── templates.ts   # Email templates
│   │       └── webhooks.ts    # SES webhooks
│   ├── core/                  # Business logic
│   │   ├── mailer.ts          # Email sending
│   │   ├── templates.ts       # Template rendering
│   │   ├── events.ts          # Event tracking
│   │   ├── metrics.ts         # Metrics collection
│   │   ├── suppression.ts     # Suppression rules
│   │   └── webhookSecurity.ts # Webhook verification
│   ├── workers/               # Background jobs
│   │   ├── emailWorker.ts     # Email processor
│   │   ├── queue.ts           # Queue setup
│   │   └── redis.ts           # Redis connection
│   ├── db/
│   │   └── client.ts          # Prisma client
│   ├── middleware/
│   │   ├── apiKeyAuth.ts      # API key auth
│   │   ├── errorHandler.ts    # Error handling
│   │   └── validation.ts      # Request validation
│   ├── utils/
│   │   ├── config.ts          # Config loader
│   │   ├── env.ts             # Env validation
│   │   ├── logger.ts          # Pino logger
│   │   ├── schemas.ts         # Zod schemas
│   │   └── validation.ts      # Validators
│   └── scripts/
│       ├── seed.ts            # Database seeding
│       ├── generateApiKey.ts  # Key generation
│       └── cleanupDLQ.ts      # DLQ cleanup
├── prisma/
│   └── schema.prisma          # Database schema
├── Dockerfile                 # Container image
├── docker-compose.yml         # Multi-container setup
├── package.json              # Dependencies
├── tsconfig.json             # TypeScript config
└── .env                      # Environment config

🧪 Testing & Verification

▼

Health Checks (No Auth Required)

# Liveness check
curl http://localhost:3000/api/v1/health

# Readiness check (includes DB & Redis)
curl http://localhost:3000/api/v1/ready

# Metrics
curl http://localhost:3000/api/v1/metrics

Admin Authentication Test

# Generate API key first
npm run gen-key "Test Key"

# Then test auth endpoint
curl -X GET http://localhost:3000/api/v1/admin/keys \\
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limiting Test

# Send 101 requests (should fail after 100)
for i in {1..101}; do 
  curl http://localhost:3000/api/v1/health 
done

# Should see: Too many requests (429 status)

Email Batch Test

curl -X POST http://localhost:3000/api/v1/batches \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "template_id": "YOUR_TEMPLATE_ID",
    "recipients": [
      {"email": "user1@example.com", "name": "User 1"},
      {"email": "user2@example.com", "name": "User 2"}
    ]
  }'