Delivering mail to a Unix .forward file

This page is showing a generic answer.
To see a more detailed answer customized for you, type your domain name here:

Technically advanced topic

These instructions are not recommended for most users. Consider using Sieve filtering instead, which is a simpler and safer way to filter mail on the server.

Technically advanced users can deliver their email via Unix .forward files. This allows you to run a program to handle an email message every time mail arrives for a certain address.

Note that this is an advanced technique that we don't provide direct assistance with beyond the instructions below; if you aren't familiar with Unix .forward files or the concept of "piping email to an external command", you probably shouldn't do this.

Before you continue

IMPORTANT: The examples below are generic. Enter your domain name in the box above to see examples that include your domain name and the correct paths for your account.

Unix mail delivery

You can use the account management control panel to direct incoming mail for any address to the Unix local delivery agent for your account (we use the Postfix local delivery agent).

To do this:

The .forward file should be a standard Unix .forward file containing commands (it must be a regular file, not a symlink).

For example, if the .forward file contained this line:

|/home/ex/example.com/mailprog.sh

... then the program named "mailprog.sh" would run from your home directory each time mail arrived. Make sure the program is "executable" to avoid "permission denied" errors.

Other common entries might include this one to run procmail:

|/usr/bin/procmail

Or this to run a program in your website's cgi-bin folder:

|/var/www/html/ex/example.com/cgi-bin/mailprog.sh

If the command to run the program contains spaces, be sure to enclose the whole thing in quotes:

|"/home/ex/example.com/mailprog.sh --add --test"

If you prefer to save your mail messages as a .mbox file in your home directory for some reason:

~/mail.mbox

Handling multiple addresses

Each domain name only has one Unix user ID on our servers, meaning you can only have one .forward file per domain name. However, you can work around that limitation quite easily if you need to have multiple incoming addresses handled differently.

One solution is to use the address extension trick mentioned in the Postfix local delivery agent documentation to set an environment variable. For example, you could set up two forwarding addresses in the Web hosting control panel as follows:

  • address1@example.com forwards to dot-forward-file+address1@example.com
  • address2@example.com forwards to dot-forward-file+address2@example.com

This will cause the EXTENSION environment variable to be set to "address1" or "address2", and the program executed by the .forward file can use that value to decide what action to take.

If you need to run different programs for different addresses, you can make your .forward file invoke a script that runs other scripts as appropriate. For example, this shell script will run different programs depending on the EXTENSION:

#!/bin/sh

# run program1.sh if the extension is "address1"
[ "$EXTENSION" = "address1" ] && exec /home/ex/example.com/program1.sh

# run program2.pl if the extension is "address2"
[ "$EXTENSION" = "address2" ] && exec /var/www/html/ex/example.com/cgi-bin/program2.pl

# run procmail for any other address
exec /usr/bin/procmail

If you plan on using procmail or a similar program to directly create or manipulate mail files, this page explains where mail is actually stored.