Postal is a complete and fully featured mail server for use by websites & web servers. Think Sendgrid, Mailgun or Postmark but open source and ready for you to run on your own servers.
This module provides seamless integration of Postal with NethServer 8, offering:
- π Full-featured mail server - Send, receive, and manage emails
- π Built-in security - DKIM, SPF, and bounce handling
- π Comprehensive analytics - Track deliveries, opens, and clicks
- π Web-based interface - Modern UI for mail management
- π§ API access - RESTful API for integration
- π High performance - Built for scale and reliability
Install the Postal module on your NethServer 8 instance:
add-module ghcr.io/geniusdynamics/postal:latest 1
Example output:
{
"module_id": "postal1",
"image_name": "postal",
"image_url": "ghcr.io/geniusdynamics/postal:latest"
}
Configure your Postal instance (assuming instance name is postal1
):
api-cli run configure-module --agent module/postal1 --data - <<EOF
{
"host": "mail.yourdomain.com",
"http2https": true,
"lets_encrypt": true
}
EOF
Parameter | Type | Required | Description |
---|---|---|---|
host |
string | β | Fully qualified domain name (e.g., mail.example.com ) |
http2https |
boolean | β | Force HTTPS redirection |
lets_encrypt |
boolean | β | Enable Let's Encrypt SSL certificate |
After configuration, Postal will be available at:
- Web Interface:
https://your-configured-host
- SMTP: Port 2525
- IMAP: Port 2143
api-cli run get-configuration --agent module/postal1
api-cli run update-module --data '{
"module_url": "ghcr.io/geniusdynamics/postal:latest",
"instances": ["postal1"],
"force": true
}'
remove-module --no-preserve postal1
The module deploys the following containerized services:
- postal-app: Main Postal application server
- postal-smtp-app: SMTP service for sending emails
- postal-worker-app: Background worker for processing tasks
- mariadb-app: Database backend
- caddy-app: Web server and reverse proxy
- Port 5000: Internal web interface (proxied through Traefik)
- Port 2525: SMTP service
- Port 2143: IMAP service
Persistent data is stored in:
- Database files and configurations
- Mail queues and logs
- SSL certificates (if Let's Encrypt is enabled)
Postal automatically integrates with NethServer 8's smarthost configuration:
- Configuration is discovered from Redis keys
- The
bin/discover-smarthost
script refreshes settings on startup - Changes are automatically applied via event handlers
Key configuration templates:
imageroot/templates/postal.yml.j2
- Main Postal configurationimageroot/templates/Caddyfile.j2
- Web server configuration
-
Check general environment state:
runagent -m env
-
Check instance environment variables:
runagent -m postal1 env
-
Enter agent environment:
runagent -m postal1
-
View running containers:
runagent -m postal1 podman ps
-
Access container shell:
runagent -m postal1 podman exec -it postal-app /bin/bash
Inside the container, you can run:
- Initialize Postal:
postal initialize
- Create a new user:
postal make-user
- View configuration:
cat config/postal.yml
- Initialize Postal:
-
Inspect container environment:
podman exec postal-app env
-
Access container shell in sh:
podman exec -ti postal-app sh
Check specific configurations with:
cat config/postal.yml
These commands are essential for debugging and managing the Postal instance effectively.
ns8-postal/
βββ imageroot/ # Module runtime files
β βββ actions/ # Module actions (configure, restore, etc.)
β βββ bin/ # Utility scripts
β βββ events/ # Event handlers
β βββ systemd/ # Systemd service definitions
β βββ templates/ # Configuration templates
βββ ui/ # Web interface
β βββ src/ # Vue.js application source
β βββ public/ # Static assets and metadata
βββ tests/ # Automated tests
βββ build-images.sh # Image building script
Run the automated test suite:
./test-module.sh <NODE_ADDR> ghcr.io/geniusdynamics/postal:latest
Tests are implemented using Robot Framework and cover:
- Module installation and configuration
- Service health checks
- Basic functionality validation
-
Verify services are running:
runagent -m postal1 systemctl --user status postal.service
-
Check logs:
podman logs postal-app
The module supports multiple languages through Weblate.
Supported Languages:
- English (en)
- German (de)
- Spanish (es)
- Italian (it)
- Portuguese (pt, pt_BR)
- Basque (eu)
Contributing Translations:
- Join the NethServer Weblate project
- Add translations for the
postal
component - Submit pull requests for new language files
- Postal Documentation: docs.postalserver.io
- NethServer 8 Core: ns8-core documentation
- Module API Reference: Auto-generated from code comments
We welcome contributions! Please see our contribution guidelines for details.
-
Clone the repository:
git clone https://github.com/geniusdynamics/ns8-postal.git cd ns8-postal
-
Build development images:
./build-images.sh
-
Run tests:
./test-module.sh localhost:9999 postal:latest
- Issues: GitHub Issues
- Documentation: Postal Documentation
- Community: NethServer Community
- Commercial Support: support@genius.ke
This project is licensed under the GNU General Public License v3.0.
Copyright (C) 2023 Genius Dynamics
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
- Genius Dynamics - support@genius.ke
- NethServer Community - community.nethserver.org