PingMailer

Simple Email Service for Transactional Emails

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.