Eternals Mailer

In Progress

Eternals Mailer is a scalable, self-hosted email delivery service built with NestJS. It handles transactional and system emails with queue-based processing, retry logic, and template-driven sending — no third-party providers required.

Tech Stack

Layer	Technology
Application	NestJS
Database	PostgreSQL
Queue	Redis

Features

• Token-based authentication — Secure API access with scoped tokens
• Queue-based email processing — Reliable delivery via Redis-backed job queues
• Template-driven emails — Define reusable templates with variable substitution
• Retry & failure handling — Automatic retries with configurable backoff
• Environment-based configuration — 12-factor app compatible
• Webhook callbacks — Delivery status notifications

Use Cases

• OTP and authentication emails
• Notifications and system alerts
• Inter-service communication emails
• Scheduled digest emails

Architecture Overview

API Request → Auth Middleware → Email Queue (Redis) → Worker → SMTP Delivery
                                                           ↓
                                                    PostgreSQL (audit log)

Tip

Eternals Mailer implements a standard REST API, making it easy to integrate with any service that can make HTTP requests.

Quick Start

Docker

docker run -d \
  -e DATABASE_URL=postgresql://user:pass@db:5432/mailer \
  -e REDIS_URL=redis://redis:6379 \
  -e SMTP_HOST=smtp.example.com \
  -p 3000:3000 \
  eternals/mailer:latest

Docker Compose

services:
  mailer:
    image: eternals/mailer:latest
    environment:
      DATABASE_URL: postgresql://user:pass@db:5432/mailer
      REDIS_URL: redis://redis:6379
      SMTP_HOST: smtp.example.com
    ports:
      - "3000:3000"
    depends_on:
      - db
      - redis

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: mailer
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass

  redis:
    image: redis:7-alpine

API Reference

Send an Email

POST /api/emails
Authorization: Bearer <token>
Content-Type: application/json

{
  "to": "user@example.com",
  "template": "otp",
  "variables": {
    "code": "123456",
    "expires_in": "10 minutes"
  }
}

Response

{
  "id": "em_01j...",
  "status": "queued",
  "created_at": "2026-04-13T00:00:00Z"
}

Note

Full API documentation, environment variable reference, and template authoring guide are coming soon as the project reaches stable status.

Vision

Eternals Mailer aims to become a fully self-hosted alternative to email service providers like SendGrid and Mailgun — with deep integration into the Eternals ecosystem and complete audit trails for every email sent.