Author: Sam Varshavchik

## Introduction

The Courier mail server is a modular multiprotocol mail server that's designed to strike a balance between reasonable performance, flexibility and features.

## Features

- Can be configured to function as an intermediate mail relay, or as a mail server that receives mail for multiple domains and makes it accessible to mail clients, or anything in between.
- On servers with multiple IP addresses, optionally assign a vanity configuration to Courier for each IP address, making each IP address look like a separate, dedicated, mail server instance, for both incoming and outgoing mail. An alternative limited vanity configuration for outgoing mail only, based on the sending mail client's authenticated login, is possible when multiple IP addresses are not available.
- Web-based administration and configuration tool .
- Local mailboxes can be accessed via POP3. The Courier mail server includes an integrated POP3 server.
- Local mailboxes can be accessed via IMAP. The Courier mail server includes an integrated IMAP server.
- A built-in IMAP/POP3 aggregator proxy. It is possible to distribute all mailboxes between multiple servers. A separate server (or a pool of servers) accepts connections from IMAP or POP3 clients, then connects to the right server based on the mailbox the connecting client is logging into.
- Local mailboxes can be accessed via HTTP. The Courier mail server includes an integrated webmail server.
- The webmail server includes a personal event calendar.
- Uses an efficient maildir format as its native mail storage format. Some support is provided for legacy mbox mailboxes.
- Flexible "Sender Policy Framework" support; the ESMTP `HELO`, `MAIL FROM`, and the `From:` header can be validated using SPF.
- DSN, PIPELINING, and 8BITMIME ESMTP extensions. The Courier mail server automatically converts 8-bit messages to 7-bit encoding, for relaying mail to external mail gateways.
- STARTTLS ESMTP extension (as well as IMAP/POP3/ESMTP/Webmail over SSL) in both the client and the server (requires OpenSSL). The ESMTP client can optionally require that the remote server's X.509 certificate is signed by a trusted root CA (a default set of root CAs is provided).
- Experimental TLS/SSL enhancements which are designed to implement a secure mail delivery channel between trusted domains, over an untrusted network. This is implemented by requiring mail to select domains use TLS/SSL connections which require the remote server to present an X.509 certificate signed by a private (not a public) certificate authority. This is pretty much the highest level of security that can be achieved with today's technologies. This doesn't even require DNSsec. Even if the DNS cache is poisoned with MX records that divert mail to a rogue relay, the attacker will not have an X.509 certificate signed by a private CA (this assumes, of course, that the security of the private CA hasn't been breached). This work is mostly complete, but still needs a little testing.
- Message submission protocol (RFC 2476).
- IPv6 support (experimental).
- NOTE: the integrated servers work with maildir-based mailboxes only. There are many existing POP3, IMAP, and webmail servers that provide excellent support for mbox-based mailboxes, so there's no reason to reinvent the wheel. Some popular mbox servers are: Qpopper, UW-IMAP, and NeoMail.
- A faxmail gateway (experimental) that forwards E-mail messages via fax (requires a compatible class 2 faxmodem). The Courier mail server doesn't implement the actual faxing all by itself, actually. The Courier mail server uses additional software (which must be separately installed), to take care of the low-level details. The popular mgetty+sendfax package talks to the faxmodem and handles the actual faxing. Conversion of E-mail messages to fax pages is done by ghostscript, troff or groff, and the NetPBM library. The Courier mail server glues all of these pieces together in a seamless manner any time an E-mail message addressed to `<phonenumber@fax>` is received. The main textual body of the E-mail message is placed on a cover page, and any attachments are converted to fax image format and transmitted after the cover page. At this time, The Courier mail server knows how to send plain text, PDF, and Postscript attachments. GIF, JPEG, and PNG images can be sent to (one image per page). The additional software packages that were mentioned previously are usually already included in most Linux and BSD installations. In most cases no additional software really needs to be installed in order to get faxmailing up and running.
- The Courier mail server includes a mailing list manager, with fully automatic bounce processing.
- You don't need a full-blown mail server? Courier mail server's IMAP server, webmail server, and mail filter are available as independent packages that can be used with other mail servers (as long as the other mail servers store mail in maildirs). These sub-packages are assembled from the same source code tree. The only difference is the top level makefile. Note: the independent builds are not always in sync with the main the Courier mail server build at any given time. They follow their own schedule, and may include a slightly older, or even more recent, code base! Over time, however, everything always syncs together since all builds are assembled from the same source code repository.
- SOCKSv5 support. The Courier mail server can punch through a SOCKS firewall to send outgoing mail. Receiving mail through a SOCKS firewall is not yet supported. To use SOCKS you need to install the Courier mail server's Socks 5 proxy client library.
- PAM, LDAP, PostgreSQL (beta), or MySQL authentication. LDAP authentication requires OpenLDAP to be installed. LDAP-based mail routing is also supported.
- Gateway mail to/from UUCP (if compatible UUCP software is separately installed).
- Authenticated SMTP.
- `XVERP` and `XEXDATA` ESMTP extensions.
- DNS-based blacklists. Ability to exempt whitelisted IP addresses from the blacklists.
- Integrated mail filtering. An API is provided for installing arbitrary external mail filters, and the system administrator can selectively enable for any mail source (ESMTP, UUCP, locally submitted mail) for filtering. Two example mail filters are included - one written in C that uses threads, and a Perl-based filter. The system administrator can also enable the ability for individual mail recipients to specify their own mail filtering rules, using a scripting language (implemented by `maildrop`, see below). Mail filtering is implemented as an integral part of the mail server. Unwanted mail is rejected, and is not accepted by the Courier mail server for delivery (the external mail relay receives the error, and it becomes the external relay's problem as to what to do with unwanted junk mail).
- Partial ability to import `sendmail`'s aliases file, but not all aspects of `sendmail`'s aliasing is supported - like delivering to programs, for example. Still, most simple `aliases` files should be usable.
- Optional ability to import most of `Qmail`'s `.qmail` files (Courier mail server uses an almost 100% compatible local mail delivery instruction format).
- Most major components of the Courier mail server can be installed in non-default directories, allowing extreme customization for your particular environment.
- You can set a maximum number of messages to deliver simultaneously to the same host. This, in fact, is strongly encouraged so that a single nonfunctioning domain does not take up all available delivery slots. Rate limiting is implemented in the main scheduler, and applies to any transport mechanism, not just ESMTP.
- Mailing list administrators can specify a backup relay and have mail that's not immediately deliverable offloaded to a backup server (this feature needs testing/feedback).

However, it is also important to note what the Courier mail server does not have or will not support:

- `.forward` files are partially supported. The Courier mail server can import most basic `/etc/aliases` files from sendmail, but sendmail's `.forward` and `/etc/aliases` files are simply not 100% compatible with the Courier mail server's security model. Most `.forward` and `/etc/aliases` files should be acceptable, but some may not.
- `ETRN` is not, and will never be implemented. It's a hack, and is functionally incompatible with the Courier mail server's internal message dispatcher. If a mail node does not have constant network connectivity, there are better ways of arranging for mail transport than ETRN. The transient mail node should download mail via IMAP, or maybe even UUCP.
- Workarounds for known defects in other mail software. The Courier mail server will not accept mail with raw 8-bit characters in the headers, because they are illegal. There are well-defined protocols that must be used to encode 8-bit text in mail headers. Non-compliant messages may result in the Courier mail server itself issuing corrupted delivery status notifications, or mishandling the message in several other ways. Because of that corrupted mail will simply not be accepted. Neither will the Courier mail server deliver mail to domains with improperly-defined MX records, even though other mail servers ignore the bad data. Additionally, certain popular IMAP mail clients are known to not work with the Courier mail server's IMAP server, due to an improper IMAP implementation by the mail client.
- Scripting language for rewriting mail headers. Mail rewriting rules are hardcoded, and are expected to be sufficient in most cases. If you have an unusual situation that requires some oddball header rewriting, you'll have to implement it yourself.
- Support for mbox mailboxes in the POP3, IMAP, and webmail components. They support maildirs only. There are plenty of existing servers out there that read mbox mailboxes.

## Requirements

- A C++ compiler, `egcs` is recommended. Most of the Courier mail server are written in C, but several major sections are written in C++.
- GNU make. Other `make`s may work, but that's not guaranteed.
- Either the GDBM or Berkeley DB library must be available. Only certain versions of Berkeley DB API are supported, because the Berkeley DB API often changes (tested with 2.4.14 and 1.8.5). GDBM is the recommended library.
- Perl 5.
- The file system must support FIFOs. At least the file system that stores the mail queue must be able to support FIFOs. The Courier mail server will not work with AFS.
- Filesystem domain sockets must be available.
- Some optional components have additional dependencies - notably the additional software required for faxmail support (see above).

## Additional information

Here is a somewhat more detailed overview of the Courier mail server's less prominent features:

### Upgrade path

The Courier mail server can be installed on systems that were previously running sendmail or Qmail. Please note that the Courier mail server will be able to support most major features of both servers, however the Courier mail server is not, and will never be a 100%-compatible replacement for either sendmail or Qmail. The Courier mail server does not implement several legacy features of either MTA, and there are no plans to implement them in the future. The key differences are:

- sendmail

A local mail delivery agent, such as `procmail`, should be used for maximum compatibility with sendmail.

The Courier mail server expects system mailboxes to be in the users' home directories. If your system mailboxes are all stored separately, in `/var/spool/mail` or somewhere else, you'll need to use a local delivery agent such as `procmail`.

The Courier mail server uses a filesystem lock on mailbox files, The Courier mail server does not support old-fashioned dot-locking. If you need dot-locking, use `procmail` or `maildrop` (included).

- Qmail

A configuration switch allows the Courier mail server to read `$HOME/.qmail` files, however the Courier mail server's implementation is not 100% identical to Qmail's. The Courier mail server's `aliases` file is also used to implement Qmail-style virtual domains. A simple Perl script can be used to convert Qmail's `control/virtualdomains` into `aliases` entries.

The Courier mail server supports Maildirs natively.

The Courier mail server can use the `maildrop` mail filter as a local mail delivery agent. `maildrop` is optional, but, if used, The Courier mail server will take advantage of certain `maildrop`-specific features which optimize local mail delivery.

## Mail filters

The Courier mail server has hooks for optional, site-defined, mail filters. You'll have to write them yourself, though. The administrator-defined mail filters can block the message from being accepted by the Courier mail server (if messages comes in via SMTP, the SMTP server will reject it). The Courier mail server can also be configured to pause for a short period of time before attempting to deliver a message. If the mail filter detects a slew of duplicate messages coming in, the mail filter can block all future copies, and manually bounce the handful of copies from the queue. The system administrator can selectively enable filtering for any individual mail source (ESMTP, locally submitted mail, UUCP). The system administrator can also optionally enable recipient-specified mail filters. With recipient-specified mail filtering enabled, any local mail recipient can install an arbitrary mail filter to selectively accept or reject mail based on any criteria.

Currently the mail filtering API is not very well documented, but it's there.

## ESMTP extensions

The Courier mail server implements `AUTH`, `PIPELINING`, `DSN`, `SIZE`, and `8BITMIME` extensions to SMTP. The Courier mail server also includes a reference implementation of the experimental `XVERP` and `XEXDATA` extensions.

The Courier mail server is a closed mail relay by default. The Courier mail server cannot be accidentally configured as a completely open relay. A deliberate feat of stupidity is required for that to happen.

## ESMTP BOFH

The Courier mail server does not deliver mail to domains with broken MX records. The Courier mail server also refuses to accept any mail with a return address in a domain with broken MX records.

The Courier mail server can automatically blacklist domains whose mail servers reject delivery status notifications.

## Header rewriting

The Courier mail server will rewrite headers and MIME-ify messages whenever appropriate. Header rewriting logic is hardcoded in C, there is no header rewriting language as in sendmail. An interpreted language imposes a drastic speed penalty. The rewriting library is fairly simple, and the the standard rewriting rules will do for most situations.

The Courier mail server rejects messages with badly-formed or missing MIME headers. The Courier mail server rejects messages containing 8-bit characters in the headers, or messages that contain 8-bit content, but do not have the required MIME headers. Accepting malformed messages of that kind can result in the Courier mail server itself sending mail that violates the relevant RFCs, therefore Courier mail server will simply reject improperly-formatted messages. There are well-defined RFC standards that explicitly spell out how mail containing 8-bit content or 8-bit headers should be encoded, and those standards will have to be properly implemented by anyone that wishes their mail to be accepted.

## Modularity

Message scheduling, dispatching, and the actual transport mechanism are completely modularized. Different message transport mechanisms such as UUCP can be implemented in a simple plug-in fashion, however some C coding will be required.

## Message scheduling

The Courier mail server supports VERPs, multiple recipients per message, and RFC1894-compliant delivery status notifications.

## Load limiting

You can set a maximum number of messages to deliver simultaneously to the same host. This, in fact, is strongly encouraged so that a single nonfunctioning domain does not take up all available delivery slots. Rate limiting is implemented in the main scheduler, and applies to any transport mechanism, not just ESMTP.

## Automatic restarts and garbage cleanup

The Courier mail server's scheduling engine restarts itself automatically, on a regular basis. This helps with memory fragmentation. The Courier mail server tries to restart itself during periods of system inactivity.

## Smart organization of the message queue and temporary directories

The Courier mail server automatically creates subdirectories when necessary, and deletes them when they're empty. When there's a sudden peak in the number of messages added to the queue, directories used to store the messages grow in size to accomodate the additional entries. On many file systems, once those messages are deleted, the empty slack space in the directory is not reclaimed, and actually slows down subsequent directory operations. The Courier mail server automatically removes empty directories, reclaiming the slack space.

## Smart installation layout

The Courier mail server's configuration script will install the Courier mail server into `/usr/lib/courier` by default. Everything will go into several subdirectories there: the actual binaries, configuration files, the mail queue, manual pages, and auxiliary support files. Optional configuration switches allow pretty much every major subdirectory to be relocated anywhere else. For example, the Red Hat RPM package for the Courier mail server relocates the configuration files to `/etc/courier`, the manual pages to `/usr/man`, and the mail queue to `/var/spool/courier`.

## Mailing lists

The Courier mail server can implement both sendmail and qmail-style address aliases. De-duping of sendmail-style aliases is automatic. The Courier mail server source distribution also includes a complete mailing list manager.