Skip to content

README.md

Latest commit

 

History

History
93 lines (71 loc) · 2.75 KB

README.md

File metadata and controls

93 lines (71 loc) · 2.75 KB
Raw

PingMailer

Simple Email Service for Transactional Emails

License Last Commit

PingMailer is a lightweight service for sending transactional emails. It provides a simple REST API for email delivery using SMTP, powered by its own Postfix/OpenDKIM mail infrastructure.

• Features • Getting Started • Architecture • License •

Features

  • Simple REST API – Send emails via HTTPS requests
  • Template Support – Pre-built email templates for common use cases
  • SMTP Integration – Works with any SMTP server or PingMailer instance
  • Lightweight – Minimal resource footprint
  • Dockerized – Easy deployment with Docker Compose

Getting Started

Prerequisites

  • Docker and Docker Compose installed
  • SMTP server credentials (or a running PingMailer instance)

Quick Start

  1. Clone the repository

    git clone https://github.com/OpenGovMail/pingmailer.git
cd pingmailer

  2. Set up the mail infrastructure

    bash mail-infra/scripts/setup/setup.sh

  3. Start the PingMailer mail server

    bash mail-infra/scripts/service/start-pingmailer.sh

  4. Configure the API server

    cd api-server
cp .env.example .env

    Edit the .env file to set your DOMAIN for SSL certificate configuration.

  5. Start the API server

    docker compose -f docker-compose.https.yml up -d

  6. Send a test email

    curl -k -X POST https://localhost:8443/notify \
    -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "smtp_host": "your_smtp_host",
    "smtp_port": 587,
    "smtp_username": "your_smtp_username",
    "smtp_sender": "sender@example.com",
       "recipients": [
          {
             "email": "user@example.com",
             "name": "User"
          }
       ]
  }'

    The API forwards the bearer access token to SMTP using XOAUTH2.

Architecture

PingMailer consists of two main components:

  • api-server/ - Go-based REST API server for sending templated emails
  • mail-infra/ - PingMailer SMTP components for outgoing mail delivery

The API server accepts HTTPS requests and forwards emails through the configured SMTP server. Email templates are stored in api-server/internal/emailer/templates/.

License

Distributed under the Apache 2.0 License. See LICENSE for more information.