35. Headers

Contents:
The H Configuration Command
Header Names
Header Field Contents
?flags? in Header Definitions
Header Behavior in conf.c
Headers by Category
Forwarding with Resent-Headers
Precedence
Pitfalls
Alphabetized Reference

All mail messages are composed of two distinct parts: the header (containing information such as who the message is from) and the body (the actual text of the message). The two parts are separated from each other by a single blank line (although there are exceptions, which we will cover). The header part used by sendmail is mainly defined by RFC822 with some minor clarification contained in RFC1123. These two documents detail the required syntax and contents of most header lines in mail messages. Many other RFCs define other headers, but in this chapter we will discuss header lines as they relate specifically to sendmail, referencing other RFCs as necessary.

When sendmail receives a mail message, it gathers all the header lines from that message and saves them internally. Then, during queueing and delivery, it recreates them and augments them with any new ones that may be required either by the configuration file or by sendmail's internal logic.

35.1 The H Configuration Command

The H header configuration file command tells sendmail which headers are required for inclusion in the header portion of mail messages. Some headers, such as Date:, are added only if one is not already present. Others, such as Received: (see Section 35.10.25, Received:) are added even if one or more are already present.

The form for the header command is:

H?flags?name:field

The H must begin the line. The optional ?flags? (the question marks are literal), if present, must immediately follow the H with no intervening space. We will discuss header ?flags? after the name and field are explained.

The name is the name of the header, such as From. The name must immediately follow the ?flags?, if present, or the H if there are no flags.

A colon then follows, which may be surrounded by optional space characters. The field is last and constitutes everything from the first nonspace character following the colon to the end of the line:

Hname   :   field
            
            from here to end of line is the field

The colon must be present. If it is absent, sendmail prints the following error message and ignores that H command:

header syntax error, line "offending H command here"

The "offending H command here" is the full text of the H command in the configuration file that caused the error.

As with all configuration commands, a line that begins with a space or a tab is joined to the line above. In this way, header commands can be split over one or more lines:

HReceived: $?sfrom $s $.by $j ($v/$V)
      id $i; $b
  
  tab

When these two lines are read from the configuration file by sendmail, they are internally joined to form the single line:

HReceived: $?sfrom $s $.by $j ($v/$V)\n      id $i; $b
                                          
                                          tab

The \n above illustrates that when lines are joined, the newline and tab character are retained. This results in the header looking the same as it did in the configuration file (minus the leading H) when it is later emitted by sendmail.