Hermes

Mailer micro-service for vandeas

Table of content

• Environment Variables
• Desktop Application
• Documentation
  • Supported Mail Providers
  • Contact Form
    • Example of CONTACT_FORM_CONFIGS_FOLDER Configuration Files
  • Mail Config
    • Example of MAIL_CONFIGS_FOLDER Configuration Files
  • Mail Template
• API Reference
  • Send Contact Form Using Contact Form Configuration
    • POST /v1/mail/contact
    • Body Parameters
  • Send Mail Using Mail Configuration
    • POST /v1/mail
    • Body Parameters
  • Send Batch of Mails Using Mail Configurations
    • POST /v1/mail/batch
    • Body Parameters
• Roadmap
  • Completed and Pending Features

Environment Variables

To run this project, you will need to add the following environment variables

• CONTACT_FORM_CONFIGS_FOLDER: An existing folder in your file system where the contact form configs will be stored.
• MAIL_CONFIGS_FOLDER: An existing folder in your file system where the email configs will be stored.
• TEMPLATES_FOLDER: An existing folder in your file system where the email templates will be stored.
• GOOGLE_RECAPTCHA_SECRET: A Google ReCaptcha secret (required only when using Google ReCaptcha in contact forms).
• USE_MAIL_QUEUE: (Optional, default: true) Enable queue-based email sending with rate limiting.
• MAIL_RATE_LIMIT: (Optional, default: 10) Maximum number of emails to send per second.

See .env.example for a complete configuration template.

Mail Queue System

Hermes includes a built-in queue system with rate limiting for email sending. See MAIL_QUEUE_SYSTEM.md for detailed documentation.

Desktop Application

Hermes now includes a Compose Multiplatform desktop application for managing mail templates and configurations via SSH!

Features

• Remote Management: Connect to your server via SSH and manage files remotely
• Template Editor: Browse, edit, create, and delete mail templates (.hbs files)
• Config Management: Manage mail and contact form configuration files (JSON)
• Modern UI: Material 3 design with intuitive tabbed navigation
• Persistent Settings: Saves your SSH connection settings locally

Quick Start

# Run the desktop application
./gradlew desktop:run

# Build native installer
./gradlew desktop:packageDistributionForCurrentOS

For detailed documentation, see desktop/README.md.

Documentation

Supported Mail Providers

• Sendgrid Removed due to lack of support for batch emails requests
• Resend
• Custom SMTP server, that can be configured in the email & contact form configs

Contact Form

Contact forms support captcha validation with the following providers:

• Google ReCaptcha - Requires GOOGLE_RECAPTCHA_SECRET environment variable
• Kerberus - Alternative captcha provider

Example of CONTACT_FORM_CONFIGS_FOLDER configuration files

Resend-based config

{
    "id": "UUID",
    "dailyLimit": 10,
    "destination": "john@example.com",
    "sender": "doe@example.com",
    "threshold": 0.5, // ReCaptcha score threshold
    "lang": "fr", // ISO 639-1
    "subjectTemplate": "New mail from {{form.firstName}}",
    "provider": "RESEND",
    "apiKey": "<YOUR_RESEND_API_KEY>"
}

SMTP-based config

{
    "id": "UUID",
    "dailyLimit": 10,
    "destination": "john@example.com",
    "sender": "doe@example.com",
    "threshold": 0.5, // ReCaptcha score threshold
    "lang": "fr", // ISO 639-1
    "subjectTemplate": "New mail from {{form.firstName}}",
    "provider": "SMTP",
    "username": "<SMTP_USERNAME>",
    "password": "<SMTP_PASSWORD>",
    "smtpHost": "<SMTP_SERVER_IP>",
    "smtpPort": "<SMTP_SERVER_PORT>"
}

Filename does not have to respect any convention.

Mail config

Example of MAIL_CONFIGS_FOLDER configuration files

Resend-based config

{
    "id": "UUID",
    "sender": "no-reply@example.com",
    "subjectTemplate": "New mail from {{form.firstName}}",
    "provider": "RESEND",
    "apiKey": "<YOUR_RESEND_API_KEY>"
}

SMTP-based config

{
    "id": "UUID",
    "sender": "no-reply@example.com",
    "subjectTemplate": "New mail from {{form.firstName}}",
    "provider": "SMTP",
    "username": "<SMTP_USERNAME>",
    "password": "<SMTP_PASSWORD>",
    "smtpHost": "<SMTP_SERVER_IP>",
    "smtpPort": "<SMTP_SERVER_PORT>"
}

Mail template

Filename should be {{UUID}}.hbs (same UUID as the id field in the Contact Form or Mail config)

API Reference

Send contact form using contact form configuration

POST /v1/mail/contact

Body

Attribute	Type	Description
id	string	Required. Your contact form config id
fullName	string	Required Full name of the person that sent the form
email	string	Required Email of the person that sent the form
content	string	Required Content of the message
recaptchaToken	string	Required Result token/secret of recaptcha

Send mail using mail configuration

POST /v1/mail

Body

Attribute	Type	Description
id	string	Required. Your mail config id
email	string	Required Email of the person to sent the mail to
attributes	Map<string, string> / JSON Object	Required Attributes to hydrate the mail template

Send batch of mails using mail configurations

POST /v1/mail/batch

Body

Attribute	Type	Description
mails	Array<Mail>	Required. Array of mails to send

[
    {
        "id": "UUID", // Mail config id
        "email": "johndoe@example.com",
        "attributes": {
            "firstName": "John",
            "lastName": "Doe"
        }
    }
]

Roadmap

• Better templating system (currently stored in /resources/templates)
• Endpoint to send email
• Desktop application to manage templates and configs via SSH
• Queue system with rate limiting for email sending
• Watch and reload configuration files and templates