---
name: "dot-qmail"
section: "5"
platform: "linux"
package: "qmail"
version: "1.06-6.2~deb10u1"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/dot-qmail"
---

# dot-qmail(5)

control the delivery of mail messages

## NAME

dot-qmail - control the delivery of mail messages

## DESCRIPTION

Normally the **qmail-local** program delivers each incoming message to your system mailbox, *homedir**/Mailbox***, where *homedir* is your home directory.

It can instead write the mail to a different file or directory, forward it to another address, distribute it to a mailing list, or even execute programs, all under your control.

## THE QMAIL FILE

To change **qmail-local**'s behavior, set up a **.qmail** file in your home directory.

**.qmail** contains one or more lines. Each line is a delivery instruction. **qmail-local** follows each instruction in turn. There are five types of delivery instructions: (1) comment; (2) program; (3) forward; (4) mbox; (5) maildir.

- (1)

  A comment line begins with a number sign:

  ```
       # this is a comment
  ```

  **qmail-local** ignores the line.

- (2)

  A program line begins with a vertical bar:

  ```
       |preline /usr/ucb/vacation djb
  ```

  **qmail-local** takes the rest of the line as a command to supply to **sh**. See **[qmail-command(8)](/qmail-command/8.md)** for further information.

- (3)

  A forward line begins with an ampersand:

  ```
       &me@new.job.com
  ```

  **qmail-local** takes the rest of the line as a mail address; it uses **qmail-queue** to forward the message to that address. The address must contain a fully qualified domain name; it must not contain extra spaces, angle brackets, or comments:

  ```
       # the following examples are WRONG
       &me@new
       &<me@new.job.com>
       & me@new.job.com
       &me@new.job.com (New Address)
  ```

  If the address begins with a letter or number, you may leave out the ampersand:

  ```
       me@new.job.com
  ```

  Note that **qmail-local** omits its new **Return-Path** line when forwarding messages.

- (4)

  An  *mbox* line begins with a slash or dot, and does not end with a slash:

  ```
       /home/djb/Mailbox.sos
  ```

  **qmail-local** takes the entire line as a filename. It appends the mail message to that file, using **flock**-style file locking if possible. **qmail-local** stores the mail message in *mbox* format, as described in **[mbox(5)](/mbox/5.md)**.

  **WARNING:** On many systems, anyone who can read a file can **flock** it, and thus hold up **qmail-local**'s delivery forever. Do not deliver mail to a publicly accessible file!

  If **qmail-local** is able to lock the file, but has trouble writing to it (because, for example, the disk is full), it will truncate the file back to its original length. However, it cannot prevent mailbox corruption if the system crashes during delivery.

- (5)

  A *maildir* line begins with a slash or dot, and ends with a slash:

  ```
       /home/djb/Maildir/
  ```

  **qmail-local** takes the entire line as the name of a directory in *maildir* format. It reliably stores the incoming message in that directory. See **[maildir(5)](/maildir/5.md)** for more details.

If **.qmail** has the execute bit set, it must not contain any program lines, *mbox* lines, or *maildir* lines. If **qmail-local** sees any such lines, it will stop and indicate a temporary failure.

If **.qmail** is completely empty (0 bytes long), or does not exist, **qmail-local** follows the *defaultdelivery* instructions set by your system administrator; normally *defaultdelivery* is **./Mailbox**, so **qmail-local** appends the mail message to **Mailbox** in *mbox* format.

**.qmail** may contain extra spaces and tabs at the end of a line. Blank lines are allowed, but not for the first line of **.qmail**.

If **.qmail** is world-writable, **qmail-local** stops and indicates a temporary failure.

## SAFE QMAIL EDITING

Incoming messages can arrive at any moment. If you want to safely edit your **.qmail** file, first set the sticky bit on your home directory:

```
     chmod +t $HOME
```

**qmail-local** will temporarily defer delivery of any message to you if your home directory is sticky (or group-writable or other-writable, which should never happen). Make sure to

```
     chmod -t $HOME
```

when you are done! It's a good idea to test your new **.qmail** file as follows:

```
     qmail-local -n $USER ~ $USER '' '' '' '' ./Mailbox
```

## EXTENSION ADDRESSES

In the **qmail** system, you control all local addresses of the form *user**-**anything*, as well as the address *user* itself, where *user* is your account name. Delivery to *user**-**anything* is controlled by the file *homedir/**.qmail-**anything*. (These rules may be changed by the system administrator; see [**qmail-users**(5)](/qmail-users/5.md).)

The **alias** user controls all other addresses. Delivery to *local* is controlled by the file *homedir/**.qmail-**local*, where *homedir* is **alias**'s home directory.

In the following description, **qmail-local** is handling a message addressed to *local@domain*, where *local* is controlled by **.qmail-*ext***. Here is what it does.

If **.qmail-*ext*** is completely empty, **qmail-local** follows the *defaultdelivery* instructions set by your system administrator.

If **.qmail-*ext*** doesn't exist, **qmail-local** will try some default **.qmail** files. For example, if *ext* is **foo-bar**, **qmail-local** will try first **.qmail-foo-bar**, then **.qmail-foo-default**, and finally **.qmail-default**. If none of these exist, **qmail-local** will bounce the message. (Exception: for the basic *user* address, **qmail-local** treats a nonexistent **.qmail** the same as an empty **.qmail**.)

**WARNING:** For security, **qmail-local** replaces any dots in *ext* with colons before checking **.qmail-*ext***. For convenience, **qmail-local** converts any uppercase letters in *ext* to lowercase.

When **qmail-local** forwards a message as instructed in **.qmail-*ext*** (or **.qmail-default**), it checks whether **.qmail-*ext*-owner** exists. If so, it uses *local**-owner@**domain* as the envelope sender for the forwarded message. Otherwise it retains the envelope sender of the original message. Exception: **qmail-local** always retains the original envelope sender if it is the empty address or **#@\[\]**, i.e., if this is a bounce message.

**qmail-local** also supports **variable envelope return paths** (VERPs): if **.qmail-*ext*-owner** and **.qmail-*ext*-owner-default** both exist, it uses *local**-owner-@**domain**-@\[\]*** as the envelope sender. This will cause a recipient *recip**@**reciphost* to see an envelope sender of *local**-owner-**recip**=**reciphost**@**domain*.

## ERROR HANDLING

If a delivery instruction fails, **qmail-local** stops immediately and reports failure. **qmail-local** handles forwarding after all other instructions, so any error in another type of delivery will prevent all forwarding.

If a program returns exit code 99, **qmail-local** ignores all succeeding lines in **.qmail**, but it still pays attention to previous forward lines.

To set up independent instructions, where a temporary or permanent failure in one instruction does not affect the others, move each instruction into a separate **.qmail-*ext*** file, and set up a central **.qmail** file that forwards to all of the **.qmail-*ext***s. Note that **qmail-local** can handle any number of forward lines simultaneously.

## SEE ALSO

[envelopes(5)](/envelopes/5.md), [maildir(5)](/maildir/5.md), [mbox(5)](/mbox/5.md), [qmail-users(5)](/qmail-users/5.md), [qmail-local(8)](/qmail-local/8.md), [qmail-command(8)](/qmail-command/8.md), [qmail-queue(8)](/qmail-queue/8.md), [qmail-lspawn(8)](/qmail-lspawn/8.md)