Postal Server: An In-Depth Technical Guide to the Open-Source Mail Delivery Platform


In the era of digital communication, managing and delivering emails efficiently is crucial for businesses and organizations. Postal, an open-source mail delivery platform, provides a robust solution for handling email servers, managing multiple organizations, and ensuring high deliverability. This technical blog post will delve into the comprehensive features of Postal, its installation process, and its operational capabilities, offering a detailed overview for users looking to harness its power for their email needs.

What is Postal?

Postal is an open-source mail delivery platform designed to manage and deliver large volumes of emails efficiently. It supports multiple organizations, offers detailed logging and monitoring, and provides extensive configuration options to meet various email delivery requirements. Built with modern technologies, Postal is capable of handling both outgoing and incoming emails with features such as DKIM signing, suppression lists, click and open tracking, and spam filtering.

Key Features

General Features

Postal is packed with features that cater to both administrative and operational needs. Here are some of its general capabilities:

  1. Multi-Organization Support: Postal allows the creation of multiple organizations, each with its own mail servers and users. This is particularly useful for service providers who manage email delivery for various clients.
  2. Graphs and Statistics: The platform provides detailed graphs and statistics showing the volume of incoming and outgoing mail, helping administrators monitor email traffic effectively.
  3. Historical Message Access: Users can view historical messages, which is essential for tracking and debugging email delivery issues.
  4. Message Queue Management: Postal gives access to both outgoing and incoming message queues, enabling administrators to manage email flow and resolve any queue-related issues.
  5. Webhooks: Users can set up webhooks to receive real-time delivery information. Postal also stores the last seven days of webhook requests for debugging purposes.
  6. DNS Checking and Monitoring: Built-in DNS checking ensures that domains are correctly configured for maximum email deliverability.
  7. Retention Configuration: Administrators can configure retention policies to manage how long messages are kept in the database and the maximum size to keep on disk.
  8. Complete Logging: Comprehensive logging features help identify delivery issues quickly.
  9. Search Tools: Mail server-wide search tools make it easy to find specific messages that need investigation.

Outgoing Emails

Handling outgoing emails is a core function of Postal. Here are some of the features related to outgoing email management:

  1. SMTP and HTTP API: Messages can be sent to the SMTP server or using the HTTP API, providing flexibility in how emails are delivered.
  2. Multiple Credentials Management: Users can manage multiple credentials per server, which is useful for handling different email accounts or services.
  3. DKIM Signing: Postal supports DKIM signing of outbound messages, enhancing email security and deliverability.
  4. Development Mode: This feature allows messages to be held in Postal without actually delivering them, which is useful for testing.
  5. Suppression List: A built-in suppression list prevents sending emails to invalid or non-existent recipients.
  6. Click and Open Tracking: This feature tracks when recipients open emails and click links, providing valuable engagement metrics.
  7. Send Limits: Administrators can configure per-server send limits to avoid abuse and ensure server health.
  8. IP Address Management: Postal supports multiple pools of sending IP addresses, allowing different senders or recipients to have emails delivered from specific IP addresses.
  9. Mail Tagging: Emails can be tagged for grouping and easier management. For example, tagging emails as "receipts" or "password-reset".

Incoming Emails

Postal also excels in handling incoming emails with the following features:

  1. Forwarding to HTTP Endpoints: Incoming emails can be forwarded to HTTP endpoints for processing by web applications.
  2. Forwarding to SMTP Servers: Emails can be forwarded to other SMTP servers, enabling integration with other email systems.
  3. Forwarding to Email Addresses: Incoming emails can also be forwarded to other email addresses.
  4. Spam and Thread Checking: Postal uses SpamAssassin and ClamAV for spam and thread checking, with configurable thresholds and various methods for handling spam messages.

Installation and Setup

Setting up Postal involves several steps, from installing prerequisites to configuring the server. Here is a detailed guide to help you get started.


Before installing Postal, ensure you have the following:

  1. Dedicated Server: It's recommended to install Postal on a dedicated server with at least 4GB of RAM, 2 CPU cores, and 25GB of disk space. Ensure your provider does not block port 25 outbound.
  2. Operating System: You can use any operating system that supports Docker, as Postal runs entirely using containers.
  3. Docker: Install Docker Engine on your server. Follow the instructions on the Docker website.
  4. Docker Compose: Ensure you have the Docker Compose plugin installed.

Installing Postal

Step 1: Install Docker and System Utilities

First, install Docker and necessary system utilities. On Ubuntu/Debian:

sudo apt update
sudo apt install docker-compose git


sudo yum update
sudo yum install docker docker-compose git

Step 2: Clone the Postal Installation Helper Repository

Clone the Postal installation helper repository and link the Postal command:

git clone /opt/postal/install
sudo ln -s /opt/postal/install/bin/postal /usr/bin/postal

Step 3: Install and Configure MariaDB

Postal requires MariaDB (version 10.6 or higher). You can run MariaDB in a container:

docker run -d \
   --name postal-mariadb \
   -p \
   --restart always \
   -e MARIADB_DATABASE=postal \
   -e MARIADB_ROOT_PASSWORD=your_secure_password \

Ensure MariaDB is configured with innodb_log_file_size set to at least 10 times the biggest message size you wish to send.

Step 4: Generate Postal Configuration

Run the following command to generate initial configuration files, replacing with your actual domain:

postal bootstrap

This generates three files in /opt/postal/config:

  • postal.yml
  • signing.key
  • Caddyfile

Edit postal.yml to include your database passwords and other configuration details.

Step 5: Initialize the Database

Run the following commands to initialize the database and create your first admin user:

postal initialize
postal make-user

Step 6: Start Postal

Run Postal with the following command:

postal start

Use postal status to check the status of Postal components.

Step 7: Configure SSL with Caddy

To handle SSL termination and web traffic, use Caddy:

docker run -d \
   --name postal-caddy \
   --restart always \
   --network host \
   -v /opt/postal/config/Caddyfile:/etc/caddy/Caddyfile \
   -v /opt/postal/caddy-data:/data \

Caddy will issue an SSL certificate for your domain, allowing immediate access to the Postal web interface.

Operational Capabilities

Managing Organizations and Users

Postal supports multiple organizations, each with its own mail servers and users. This segmentation is useful for email service providers or large organizations with distinct departments. Administrators can easily manage organizations, assign mail servers, and create user accounts with specific permissions.

Monitoring Email Traffic

The platform provides detailed graphs and statistics showing the volume of incoming and outgoing mail. These visualizations help administrators monitor email traffic, identify trends, and detect any anomalies that may indicate issues such as spam or server abuse.

Message Queues

Postal offers access to both outgoing and incoming message queues. Administrators can view the status of messages, manage delivery priorities, and troubleshoot any stuck or failed messages. This capability is crucial for maintaining smooth email delivery operations.

Webhooks for Real-Time Notifications

Webhooks can be configured to provide real-time notifications about email delivery statuses. This feature is particularly useful for integrating Postal with other applications or monitoring systems. Additionally, Postal stores the last seven days of webhook requests, allowing administrators to debug and analyze recent events.

DNS Monitoring

Proper DNS configuration is critical for email deliverability. Postal includes built-in DNS checking and monitoring tools to ensure that domains are correctly configured. This feature helps maintain high deliverability rates and reduces the chances of emails being marked as spam.

Retention Policies

Administrators can configure retention policies to manage how long messages are kept in the database and the maximum disk space usage. These policies help in maintaining server performance and ensuring compliance with data retention regulations.

Logging and Search Tools

Postal provides comprehensive logging features that capture detailed information about email deliveries. This logging capability is essential for troubleshooting delivery issues, identifying spam, and ensuring compliance with email regulations. Additionally, mail server-wide search tools allow administrators to quickly find specific messages for investigation.

Outgoing Email Management


Postal supports sending messages via SMTP or HTTP API. This flexibility allows developers to choose the method that best suits their application or infrastructure. The SMTP server can handle traditional email clients and applications, while the HTTP API is suitable for modern web applications and services.

DKIM Signing

To enhance email security and deliverability, Postal supports DKIM signing for outbound messages. DKIM (DomainKeys Identified Mail) helps verify that the email has not

been altered in transit and is indeed from the claimed domain. This reduces the chances of emails being marked as spam and improves trust with recipients.

Suppression Lists

Postal includes a built-in suppression list to avoid sending emails to invalid or non-existent recipients. This feature helps maintain clean mailing lists, reduces bounce rates, and improves overall deliverability.

Click and Open Tracking

Tracking recipient engagement is crucial for measuring the success of email campaigns. Postal's click and open tracking feature records when recipients open emails and click on links. These metrics provide valuable insights into email performance and recipient behavior.

IP Address Management

For organizations with multiple email campaigns or services, managing IP addresses is essential. Postal supports multiple pools of sending IP addresses, allowing different senders or recipients to have emails delivered from specific IPs. This feature helps manage reputation and avoid blacklisting.

Mail Tagging

Mail tagging allows administrators to categorize emails for easier management and analysis. For example, emails can be tagged as "receipts" or "password-reset." Tags help group related emails, making it easier to apply specific policies or analyze performance metrics for different types of messages.

Incoming Email Management

Forwarding to HTTP Endpoints

Incoming emails can be forwarded to HTTP endpoints, enabling seamless integration with web applications. This feature is useful for processing emails in real-time, such as handling support requests, automating workflows, or triggering notifications.

Forwarding to SMTP Servers

Postal supports forwarding incoming emails to other SMTP servers. This capability allows integration with existing email systems or routing emails to specific servers for further processing.

Spam and Threat Checking

To protect against spam and malicious emails, Postal uses SpamAssassin and ClamAV for spam and threat checking. Administrators can configure thresholds and choose different methods for handling spam messages, such as marking them, moving them to a spam folder, or rejecting them outright.


Postal is a powerful and flexible open-source mail delivery platform designed to meet the needs of modern email management. With its extensive features, including multi-organization support, detailed logging, real-time notifications, and comprehensive email handling capabilities, Postal is well-suited for businesses and service providers alike. By following the installation and configuration steps outlined in this guide, you can set up Postal to efficiently manage and deliver your email communications.

For more information and detailed documentation, visit the Postal documentation site. Whether you're looking to replace an existing email server or start a new email delivery project, Postal offers a robust solution that can be tailored to your specific needs.

Next Post Previous Post
No Comment
Add Comment
comment url