Product docs and API reference are now on Akamai TechDocs.
Search product docs.
Search for “” in product docs.
Search API reference.
Search for “” in API reference.
Search Results
 results matching 
 results
No Results
Filters
How to Install and Use Postal
Traducciones al EspañolEstamos traduciendo nuestros guías y tutoriales al Español. Es posible que usted esté viendo una traducción generada automáticamente. Estamos trabajando con traductores profesionales para verificar las traducciones de nuestro sitio web. Este proyecto es un trabajo en curso.
Many small organizations want to use a self-hosted mail server to send and receive emails instead of a cloud-based mail service. Postal is a fully-featured open-source email platform that is free to install and operate. This guide explains how to install, configure, and use Postal. Additionally, it provides information about the various DNS records that are also required.
What is Postal?
Postal is a self-hosted email platform. It can be used in conjunction with a website or as a stand-alone application. Postal is a robust and secure alternative to corporate cloud-based email solutions such as Gmail and Outlook. Operating a private mail server provides flexibility and freedom, but is a lot more work. It is a task more geared toward experienced server administrators.
Postal was originally developed by the Krystal organization for its own internal use. However, due to its popularity, Postal is now available to everyone as a free open-source application. Postal can send and receive emails and can forward incoming mail to a different server or address. Postal is highly scalable and features good capacity and throughput. For ease of use and configuration, Postal is distributed as a Docker container. It can only be used with Docker and Docker Compose. Postal works in conjunction with a relational database, RabbitMQ, and a web proxy. These applications can run inside Docker containers or as independent applications.
Some of the most popular Postal features include the following:
- Support for multiple organizations, credentials, and domains.
- A dashboard with stats and graphs about incoming and outgoing mail.
- Archival access to all messages, both sent and received and the current message queues.
- Webhooks to monitor live delivery rate statistics.
- Verification tools to ensure DNS Records are correct along with suggestions to increase deliverability.
- Configurable retention settings.
- Mail archive search tools.
- Click and open tracking.
- Message delivery logs.
- Rate limiting for outgoing messages.
- The ability to send messages from SMTP or the HTTP API.
- A separate queue for held messages.
- Mail tagging.
- DKIM signing of outgoing messages.
- Mail forwarding to external emails, other mail servers, and HTTP endpoints.
- Spam analysis of incoming messages using SpamAssassin.
Postal is not a mailing list manager and does not offer list-related features such as auto-unsubscribe. Mailing lists are best managed with more specialized applications. For a full list of all Postal features, see the Postal Feature List .
Before You Begin
If you have not already done so, create a Linode account and Compute Instance. See our Getting Started with Linode and Creating a Compute Instance guides.
Follow our Setting Up and Securing a Compute Instance guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.
Create and configure a domain name and point it at the Linode. The Postal server requires several additional subdomains which are described in a subsequent section of this guide. For more information on domains and how to create a DNS record, see the Linode DNS Manager guide .
To send emails from a server, TCP port 25 must be enabled on the Linode. This is the well-known port for Simple Mail Transfer Protocol (SMTP). Postal send outgoing emails and listens for incoming mail on this port. Contact Linode support to determine whether this port is restricted on your server.
Postal requires at least four GB of RAM, two CPU cores, and at least 100GB of disk space. For best performance, run Postal on a dedicated server that is not handling other tasks.
sudo
. If you are not familiar with the sudo
command, see the Linux Users and Groups
guide.How to Install Postal
To install Postal, first install a series of prerequisites, including Docker. Postal is designed to work with Docker and cannot be used without it. After Postal is installed, a number of configuration changes must be made. These instructions are geared for Ubuntu users but are generally applicable to most distributions.
The main steps required to install Postal are as follows:
- Configure the relevant DNS records.
- Install Docker.
- Download and run the Postal container and containers for other required components.
- Configure Postal.
After the configuration is complete, the Postal web portal can be used to complete the configuration and use the application.
How to Configure DNS Records for Postal
In addition to the main A/AAAA records for the primary domain, Postal requires a few additional DNS records. Certain other optional records are highly recommended to ensure reliable delivery. These records can be created either before or after installing Postal. However, it is a good idea to create them in advance to allow time for propagation. To determine how to create the various types of DNS records from the Linode dashboard, consult the Linode DNS Manager guide .
To enable a successful Postal deployment, create the following records. For the entirety of this section, replace example.com
with the name of your domain wherever it occurs.
A/AAAA Record(s): Although the base domain can be used as the main Postal domain, it is a better idea to create a
postal
subdomain for the mail server. To create this domain, add an A record forpostal.example.com
and point it at the IPv4 address of the Linode. Create an AAAA Ipv6 DNS record for thepostal.example.com
address and point it at the Ipv6 address.SPF Record: An SPF record is a type of DNS text (TXT) record. It confirms a given server is allowed to send mail from a domain. Although this record is technically not mandatory, mail from a domain without this record might be recorded as spam and discarded. Create a TXT record for the domain
spf.postal.example.com
, and add the followingValue
to the record. Replaceipv4address
andipv6address
with the correct addresses for the domain in the following string.v=spf1 ip4:ipv4address ip6:ipv6address ~all
Main Domain SPF record: The entire
postal
domain also requires an SPF record. This record must reference thespf.postal
record created in the previous step. Create a TXT record for thepostal.example.com
domain and provide the followingValue
, replacingexample.com
with the real domain name.v=spf1 a mx include:spf.postal.example.com ~all
Return Path (RP) Records: For outgoing messages, Postal populates the
MAIL_FROM
field with the name of the return path domain. Create an A record for therp.postal.example.com
domain and point it at the IPv4 address of the server. Create a corresponding AAAA record for the samerp.postal.example.com
domain and set the value to the IPv6 address of the server. The return path domain requires another SPF/TXT record. Create a TXT record forrp.postal.example.com
and add the following information. This domain name must match the domain name of the original SPF record.v=spf1 a mx include:spf.postal.example.com ~all
Route Domain (MX) Record: A Mail Exchange (MX) record indicates the mail servers for a domain. Any email messages intended for addresses within this domain are sent to this server. Create a
MX
record for thepostal.example.com
domain. For theMail Server
field, enterpostal.example.com
. For thesubdomain
field, also enterpostal.example.com
. As in the rest of these examples, replaceexample.com
with your domain name. For thePreference
, enter10
.Return Path Domain Key Records: Postal also requires a TXT record for a
postal._domainkey.postal.example.com
domain. However, this record cannot be created yet. It requires an internal value from Postal that is only generated after Postal is installed. Therefore, the guide explains how to add this record at a later time.CNAME Record: A CNAME record helps improve the deliverability of incoming mail. It maps an alias to a real hostname. Create a CNAME record for the
psrp.postal.example.com
domain. Set the alias torp.postal.example.com
.
How to Install Docker
Follow these steps to install Docker and prepare the system for Postal. These steps install the Docker Engine and Docker Compose. The Docker Dashboard is not required and is not covered in these instructions.
Ensure the system packages are up to date.
sudo apt update -y && sudo apt upgrade -y
Ensure any pre-existing releases of Docker and related components are removed.
sudo apt-get remove docker docker-engine docker.io containerd runc
Install the additional packages required to run Docker. These packages might already be installed.
sudo apt install ca-certificates curl gnupg lsb-release
Add the official Docker GPG key.
sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
Add the Docker repository to the Ubuntu package list.
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Update the new package.
Note If any error occurs during this step, it might be due to incorrect file permissions for the public key. To correct this problem, run the commandsudo chmod a+r /etc/apt/keyrings/docker.gpg
.sudo apt update
Install Docker Engine, Docker Compose, and some other supporting utilities.
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin sudo apt install docker-compose
To validate the Docker installation, run the
hello-world
image usingdocker run
. If the installation is successful, the output should containHello from Docker!
.sudo docker run hello-world
Unable to find image 'hello-world:latest' locally latest: Pulling from library/hello-world ... Status: Downloaded newer image for hello-world:latest Hello from Docker! This message shows that your installation appears to be working correctly.
How to Install Postal and the Other Containers
Most of the other required components are also containerized. To install Postal, follow these steps.
Use
apt
to install some additional utilities. These programs might already be installed.sudo apt install git jq
Clone the Postal installation utility repository. This repository makes it much easier to install and configure Postal.
sudo git clone https://postalserver.io/start/install /opt/postal/install sudo ln -s /opt/postal/install/bin/postal /usr/bin/postal
Postal prefers to use MariaDB as the database engine. Because Docker is already installed, install MariaDB as a Docker container. Use the
docker run
command to install MariaDB. Replaceuserpassword
with a unique secure password. Make a note of the password because it is required again later.sudo docker run -d --name postal-mariadb -p 127.0.0.1:3306:3306 --restart always -e MARIADB_DATABASE=postal -e MARIADB_ROOT_PASSWORD=userpassword mariadb
Postal relies on RabbitMQ to dispatch messages between different processes. RabbitMQ must also be installed inside a Docker container. There are many ways to configure RabbitMQ, but most of the time a single
postal
user and virtual host should suffice. In the following command, substitute a secure password foruserpassword
. Keep track of this password for future use.sudo docker run -d --name postal-rabbitmq -p 127.0.0.1:5672:5672 --restart always -e RABBITMQ_DEFAULT_USER=postal -e RABBITMQ_DEFAULT_PASS=userpassword -e RABBITMQ_DEFAULT_VHOST=postal rabbitmq:3.8
How to Configure and Initialize Postal
Postal requires some additional configuration before it can be used. Several utilities installed as part of the Postal Git repository assist with this task. Consult the Postal Documentation for more in-depth information on configuring and using Postal. To configure Postal and initialize it for first use, follow these steps.
Use the
postal bootstrap
tool to generate several configuration files. Supply the domain name for Postal as an argument. In the following command, replacepostal.example.com
with the actual domain name.Note This is the domain created in the “A/AAAA Record(s)” step of How to Configure DNS Records for the Postal Mail Server section.sudo postal bootstrap postal.example.com
Latest version is: 2.1.2 => Creating /opt/postal/config/postal.yml => Creating /opt/postal/config/Caddyfile => Creating signing private key
Edit the postal configuration file
/opt/postal/config/postal.yml
. Change the account names and passwords for MariaDB and RabbitMQ to the actual values supplied in the previousdocker run
commands. Make the following changes so the file resembles the example file. Leave the other fields unchanged.- In the
main_db
section, change thepassword
to the MariaDB password. - In the
message_db
section, change thepassword
to the MariaDB password. - In the
rabbitmq
section, change thepassword
to the RabbitMQ password. - In the DNS section, change
example.com
to the name of the domain for all entries. Themx_records
field should take the formatpostal.example.com
.track_domain
should be the same as the main Postal domain, for example,postal.example.com
.
- File: /opt/postal/config/postal.yml
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
... main_db: # Specify the connection details for your MySQL database host: 127.0.0.1 username: root password: password database: postal message_db: # Specify the connection details for your MySQL server that will be house the # message databases for mail servers. host: 127.0.0.1 username: root password: password prefix: postal rabbitmq: # Specify connection details for your RabbitMQ server host: 127.0.0.1 username: postal password: password vhost: postal dns: # Specify the DNS records that you have configured. Refer to the documentation at # https://github.com/atech/postal/wiki/Domains-&-DNS-Configuration for further # information about these. mx_records: - postal.example.com smtp_server_hostname: postal.example.com spf_include: spf.postal.example.com return_path: rp.postal.example.com route_domain: routes.postal.example.com track_domain: postal.example.com ...
- In the
Initialize the
postal
database and create the database tables using the following command.sudo postal initialize
Create an administrative user for Postal using the
make-user
command. Supply an email address, first and last name, and secure password for the administrator.sudo postal make-user
Creating postal_runner_run ... done Postal User Creator Enter the information required to create a new Postal user. This tool is usually only used to create your initial admin user. E-Mail Address : username@example.com First Name : first_name Last Name : last_name Initial Password : password User has been created with e-mail address username@example.com
Start the Postal application. The following command launches a fleet of Postal containers.
sudo postal start
Use the
postal status
command to ensure all containers are active. Verify theState
of each container isUp
.sudo postal status
Name Command State Ports ------------------------------------------------------------------ postal_cron_1 /docker-entrypoint.sh post ... Up postal_requeuer_1 /docker-entrypoint.sh post ... Up postal_smtp_1 /docker-entrypoint.sh post ... Up postal_web_1 /docker-entrypoint.sh post ... Up postal_worker_1 /docker-entrypoint.sh post ... Up
Postal requires a web proxy to handle SSL requests and terminate web traffic. Although any web server service can be used, the Postal documentation recommends Caddy. Caddy is lightweight, easy to use, and can issue its own SSL certificate. Use the following
docker run
command to install Caddy.sudo 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
Use the
docker ps
command to ensure all services are running.sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES cd2c3b48eaf7 caddy "caddy run --config …" About a minute ago Up About a minute postal-caddy 478ee698eac7 ghcr.io/postalserver/postal:2.1.2 "/docker-entrypoint.…" 8 minutes ago Up 8 minutes postal_web_1 48f49ab8f757 ghcr.io/postalserver/postal:2.1.2 "/docker-entrypoint.…" 8 minutes ago Up 8 minutes postal_requeuer_1 c1a449c876cd ghcr.io/postalserver/postal:2.1.2 "/docker-entrypoint.…" 8 minutes ago Up 8 minutes postal_cron_1 c2ae45ce0442 ghcr.io/postalserver/postal:2.1.2 "/docker-entrypoint.…" 8 minutes ago Up 8 minutes postal_worker_1 d20b54f01427 ghcr.io/postalserver/postal:2.1.2 "/docker-entrypoint.…" 8 minutes ago Up 8 minutes postal_smtp_1 1c75f28d9f08 rabbitmq:3.8 "docker-entrypoint.s…" 2 hours ago Up 34 minutes 4369/tcp, 5671/tcp, 15691-15692/tcp, 25672/tcp, 127.0.0.1:5672->5672/tcp postal-rabbitmq 7037ec75847c mariadb "docker-entrypoint.s…" 2 hours ago Up 34 minutes 127.0.0.1:3306->3306/tcp postal-mariadb
How to Use the Postal Web Interface
Before sending any mail, use the Postal web interface to create organizations, servers, users, and routes. To modify and use the web server, follow these steps.
In a web browser, navigate to the name of the Postal domain,
https://postal.example.com
. Replacepostal.example.com
with the name of the actual domain.The Postal server displays the login page. Enter the name of the administrator email address and password from the
sudo postal make-user
command.The Postal dashboard asks you to create an organization. Click the Create the first organization button to continue.
Provide a name for the organization. Click Create organization to proceed.
The organization is not yet associated with a web server. Click Build your first mail server to create one.
Postal displays the
Build a new mail server
page. Provide a name for the mail server in theName
field and leave theMode
attribute set toLive
. Click Build server to create the server.Postal confirms the mail server is now ready to go.
Add a domain for the mail server to use. Select Domains from the main menu. Postal displays a warning that the mail server does not have any domains and asks you to add one. Click Add your first domain to configure the domain.
Enter the name of the Postal domain. This is the account name to send the mail from, for example,
postal.example.com
. Click Create Domain to add the domain to the mail server.The Postal dashboard displays a list of mandatory and optional DNS records to add. Most of these domains were created earlier. However, a DKIM record is still required. This record contains a public authentication key to validate the integrity and identity of emails sent from the server.
Make a note of the DKIM domain name Postal is looking for. In this example, the domain is
postal-snzWLL._domainkey.postal.example.com
, although the stringsnzWLL
should be different for each server. Return to the Linode Dashboard and add a TXT record for the suggested domain. Paste the text supplied by Postal (beginning withv=DKIM1
) into theValue
field of the form. Add another domain for the return path key. This domain has the formatpostal-snzWLL._domainkey.rp.postal.example.com
domain, withrp
betweendomainkey
andpostal
. Enter the same information for theValue
.For additional confirmation, click the
Check my records are correct
near the top of the page. Postal performs a quick verification of the DNS configuration and displays its results. For accurate test results, ensure the test domain propagates first. If Postal reports any errors, review all DNS records and ensure they were added correctly.
How to Test the Postal Installation
Postal is now ready to send emails. To send a test email, select Messages from the menu bar and then Send Message from the submenu. Enter the address of the sender and recipient, a Subject
field, and text for the Body
. For the sender address, use the auto-generated test address. This address consists of a test
followed by the mail server domain name, for example, test@postal.example.com
. When the message is ready to send, click Send Message.
Several email test sites accept incoming mail from all domains, including Mail Tester . Use one of these sites, or your own email account, to confirm whether the test message was successfully delivered.
Postal can also receive emails. To receive emails, select Routing from the main menu. Select Address Endpoints from the menu bar and add an address endpoint to serve as a final address for forwarded emails. Then select Routes and add a route for the Test
account. The Endpoint
field tells Postal how to process the email. To accept messages and read them on the server, select the Accept message with no endpoint
option. Click Save route to save the route. Postal is now able to accept mail intended for this address.
Endpoint
in the routing configuration. Click the Help button on the Postal Dashboard for more information.Conclusion
Postal is a robust and scalable open-source mail service. It handles most incoming and outgoing mail and includes a long list of valuable features. To install Postal, download and run the Docker container. Postal requires a few additional components, including a database application and web proxy, along with a few changes to its main configuration file. Postal requires several DNS records to properly send and receive mail. For more information about the Postal, see the Online Documentation .
More Information
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
This page was originally published on