---
name: courier-mta
description: Courier MTA recipe for open-forge. Fast, scalable enterprise mail server with ESMTP, IMAP, POP3, webmail, mailing list, and basic calendar/scheduling. GPL-3.0, C. Source: https://www.courier-mta.org/
---

# Courier MTA

A fast, scalable enterprise mail and groupware server providing ESMTP, IMAP, POP3, webmail (SqWebMail), mailing list management, and basic web-based calendar/scheduling. Uses Maildir format for all mail storage. GPL-3.0 licensed, written in C. The Courier Auth Library handles all authentication. Upstream: <https://www.courier-mta.org/>. Source repo: <https://www.courier-mta.org/repo.html>

## Compatible Combos

| Infra | Runtime | Notes |
|---|---|---|
| Debian / Ubuntu | APT deb packages | Official courier-specific packages (higher revision than distro) |
| CentOS / RHEL | RPM packages | Built from official RPM spec |
| Any Linux | Build from source | tarball from courier-mta.org |

## Inputs to Collect

### Phase 1 — Preflight

| Prompt | Format | Notes |
|---|---|---|
| "Primary mail domain?" | FQDN | e.g. mail.example.com — must have PTR/MX/SPF records |
| "Additional mail domains?" | FQDN list | Virtual hosted domains |
| "TLS certificate path?" | PEM paths | Let's Encrypt or commercial cert |
| "Authentication method?" | authuserdb / PAM / LDAP / MySQL | Courier Auth Library backend |
| "Webmail?" | Yes / No | SqWebMail optional component |

### Phase 2 — Deploy

| Prompt | Format | Notes |
|---|---|---|
| "Maildir storage path?" | Directory | Courier uses Maildir format exclusively |
| "Virtual mailbox accounts?" | Yes / No | User accounts without OS users |
| "Spam filtering?" | SpamAssassin / none | Courier integrates via maildrop |

## Software-Layer Concerns

- **Maildir format**: Courier stores all mail as Maildir — not mbox. Incompatible with mbox-based tools.
- **Courier Auth Library**: Separate library handles all authentication — must configure authmodule (authuserdb, PAM, LDAP, MySQL, PostgreSQL) before any component starts.
- **Multiple components**: Courier MTA is a suite — courier (SMTP), courierimap (IMAP), courierpop3d (POP3), sqwebmail (webmail). Each runs as a separate daemon.
- **Maildrop**: Courier's mail delivery agent — handles filtering, sorting, and local delivery. Replaces procmail.
- **Higher-revision packages**: Courier's own .deb/.rpm packages have higher revision numbers than distro packages to prevent accidental upgrades to distribution versions.
- **DNS requirements**: MX, PTR (rDNS), SPF, DKIM, DMARC records needed for mail deliverability.
- **Port 25 (SMTP)**: Many VPS providers block outbound port 25 by default — request unblocking before deploying.

## Deployment

### Debian/Ubuntu (from Courier packages)

```bash
# Install dependencies
sudo apt install libgnutls28-dev libldap2-dev libmysqlclient-dev courier-authlib

# Install Courier packages (use courier.sf.net packages, not distro)
# See: https://www.courier-mta.org/install.html for current package links

# Configure authentication (edit /etc/courier/authdaemonrc)
authmodulelist="authuserdb"  # or authpam, authmysql, authldap

# Start auth daemon first
sudo service courier-authdaemon start

# Configure SMTP (/etc/courier/esmtpd)
sudo service courier start
sudo service courier-imap start
sudo service courier-pop3 start

# Enable TLS
sudo mkimapdcert    # generates self-signed IMAP cert (replace with real cert)
sudo mkcourierdcert # generates self-signed SMTP cert
```

### Create virtual mailboxes (authuserdb)

```bash
# Add a user
courieruseradmin add user@example.com
# or use userdbpw + makeuserdb:
echo "user@example.com:${HOME}/Maildir" >> /etc/courier/userdb
userdbpw | userdb user@example.com set clearpw
makeuserdb
```

### Maildrop filter (delivery)

```
# ~/.mailfilter — basic spam filter example
if (/^X-Spam-Status: Yes/)
  to "$DEFAULT/.Spam/"
to "$DEFAULT"
```

## Upgrade Procedure

1. Download new Courier .deb/.rpm packages from courier-mta.org.
2. `dpkg -i` / `rpm -U` — config files in `/etc/courier/` are preserved.
3. Restart all Courier daemons after upgrade.
4. Check https://www.courier-mta.org/changelog.html for breaking changes.

## Gotchas

- **Port 25 blocking**: VPS providers (AWS, GCP, Azure, Hetzner) commonly block outbound port 25 — request removal before testing mail delivery.
- **DNS configuration is critical**: Without correct MX, PTR, SPF, DKIM, and DMARC records, outbound mail will land in spam.
- **Auth daemon must start first**: All other Courier components depend on `courier-authdaemon` — start order matters.
- **Maildir only**: No mbox support. Existing mbox mail must be converted (e.g., with `mb2md`) before migration.
- **TLS certs**: Replace self-signed certs generated by `mkimapdcert`/`mkcourierdcert` with real Let's Encrypt certs for production.
- **Webmail (SqWebMail)**: Runs as CGI — requires a web server (Apache/NGINX) with CGI support.

## Links

- Website: https://www.courier-mta.org/
- Source repo: https://www.courier-mta.org/repo.html
- Install guide: https://www.courier-mta.org/install.html
- Changelog: https://www.courier-mta.org/changelog.html
- Courier Auth Library: https://www.courier-mta.org/authlib/
