eternalscloud/mailer repository overview

⁠What is Eternals Cloud Mailer?

Eternals Cloud Mailer is an email testing tool for developers. It captures emails sent by your application during development so you can inspect them in a clean web UI. Point your app's SMTP config at Eternals Cloud Mailer, and every outgoing email lands in your local inbox — safely, instantly.

⁠Features

• Token-based Authentication — Secure API access with JWT tokens
• Real-time Email Capture — Instant capture of all outgoing emails via SMTP
• Full Message Inspection — View HTML/text bodies, headers, and attachments
• Environment-based Configuration — Simple setup via environment variables
• Modern Web UI — Clean React interface with dark mode support

⁠Use Cases

• Test email templates — Preview and validate email layouts before production
• Debug email delivery — Inspect headers, content, and attachments during development
• Verify SMTP integration — Confirm your app's email functionality without sending real emails
• QA workflows — Review automated emails in a safe, isolated environment

⁠How to Use This Image

⁠Quick Start

docker run -d \
  --name ec-mailer \
  --restart always \
  -p 8502:8502 \
  -p 1025:1025 \
  -e POSTGRES_URL=postgresql://username:password@hostname:5432/mailer \
  -v mailer:/app/attachments \
  eternalscloud/mailer:latest

Once the container is running:

• Web UI: Open http://localhost:8502 in your browser
• SMTP Server: Configure your application to send mail to localhost:1025

⁠Connecting Your Application

Configure your application's SMTP settings to point to Eternals Cloud Mailer:

⁠Node.js (Nodemailer)

const transporter = nodemailer.createTransport({
  host: 'localhost',
  port: 1025,
  secure: false
});

⁠Python (smtplib)

import smtplib

with smtplib.SMTP('localhost', 1025) as server:
    server.sendmail(sender, recipient, message)

⁠Go (net/smtp)

err := smtp.SendMail(
    "localhost:1025",
    nil,
    sender,
    []string{recipient},
    []byte(message),
)

⁠Environment Variables

POSTGRES_URL format:

• username / password — PostgreSQL credentials
• hostname — database host or Docker service name (e.g. db in Compose, localhost on the host)
• 5432 — default PostgreSQL port
• mailer — database name

⁠Exposed Ports

⁠Volumes

Important: Mount a volume to /app/attachments to persist email attachments across container restarts.

⁠Docker Compose

A complete example with PostgreSQL database:

services:
  ec-mailer:
    image: eternalscloud/mailer:latest
    container_name: ec-mailer
    restart: always
    ports:
      - "8502:8502"
      - "1025:1025"
    environment:
      - POSTGRES_URL=postgresql://username:password@hostname:5432/mailer
    volumes:
      - mailer:/app/attachments
    depends_on:
      - db

  db:
    image: postgres:18.4
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mailer
    volumes:
      - postgres:/var/lib/postgresql/data

volumes:
  mailer:
  postgres:

In this stack, set hostname to db (the Postgres service name below). Use credentials that match POSTGRES_USER / POSTGRES_PASSWORD on the db service.

Run with:

docker compose up -d

⁠Where to Get Help

• Documentation: View full documentation⁠
• Report Issues: Submit bugs or feature requests⁠

⁠License

This project is licensed under the MIT License — see the LICENSE⁠ file for details.