Specify E-Mail Custom Header
$email_header headername headervalue|[none]
This command specifies a custom header to be used for this e-mail item. You may use multiple commands in the same FS file.
Typical uses for this command would be to supply a "reply-to" address for the e-mail item, or to supply some references which will help you identify returned items from their headers. You can also override the X-Mailer: header which CopiaFacts automatically adds. See the examples below.
The parameters on this command are used as follows:
| headername | The name of the custom header. If you are adding a header other than one of those listed in RFC5322, the name should start with 'X-'. If you do not include a colon at the end, one will be added. The 'us-ascii' character set should be used. If you override the Message-ID header, see the note below: |
| headervalue | The text which you wish to add in the header. Words in the text which contain characters not in the ASCII character set will be encoded as described in RFC2047. |
| none | A keyword which will cause the X-Mailer header to be suppressed. For any other header name, the literal 'none' would be used in the header. |
Note that double-quotes must be used if the headervalue contains embedded blanks. This command is not treated specially and any double-quotes required in the quoted text must be written as two double-quotes. For compatibility with earlier releases, an embedded double quote may also be written as `".
The default macro-expansion character on all $email... commands is an ASCII grave accent character (`).
 | To override the Message-ID header, you MUST provide a unique value: for example by including `FSNUM in the text. To comply with RFC5322, it is necessary to follow the unique value with an @-sign and the domain name, and enclose the whole string in angle-brackets. If the headervalue does not start with a < character, it will be assumed that all these elements are also absent: an @-sign, the localname, and enclosing angle backets will be added. |
Default: no special headers are added other than an X-Mailer: header.
Examples:
$email_header X-Complaints-To: nobody@sender.com
$email_header X-Errors-To: `FSNUM@sender.com
$email_header X-JobID: `JOB_INSTANCE
$email_header Comment: "This is a comment"
$email_header Reply-To: """Steve Hersee"" <steve@copia.com>"
$email_header "Disposition-Notification-To: postmaster@copia.com"
$email_header Message-ID: 123456`TIME4`FSNUM
$email_header Message-ID: <123456`TIME4`FSNUM@copia.com>
You can use the $email_header command, or the EMAIL_SET_FROM variable, to support the address group syntax added in RFC6854 for sender addresses. This type of address can not be specified an $email_from command, which only permits a single sender e-mail address.
Note that CopiaFacts does not support multiple destination addresses in a single FS file. For sending to an address list, see the topic Sending to Multiple Recipients. This also applies to the address group syntax introduced in RFC5222.
An address group for sender addresses, or a simple comma-separated list, can be specified either in an $email_header override of the From: header, or in an EMAIL_SET_FROM variable. This also allows the e-mail From: header to be set to an empty group, which most e-mail clients treat as indicating a message to which replies are not accepted.
This syntax is not compatible with E-Mail Consolidation, which may require multiple e-mails with different senders to be consolidated to the same domain.
If you wish to use the syntax described in RFC6854, please note that:
•You are responsible for creating the correct header syntax in the headervalue parameter; CopiaFacts does not check this.
•You must also follow the guidelines for the use of group syntax in From: and Sender: headers, as described in RFC 6854.
| Note also that the Sender: header is intended to indicate the person who actually sent the message. It is not the "envelope sender" specified in $email_esender [FS], which sets the SMTP command "Mail From" value, not a header in the message body. |
Examples:
RFC6854 allows a message from two managing partners of a business, Ben and Carol, that is sent by their assistant, Dave, using the address-group syntax:
$email_header From: Managing Partners:ben@example.com,carol@example.com;
$email_header Sender: dave@example.com
RFC5322 has always allowed a comma-separated list of addresses for this purpose:
$var_def EMAIL_SET_FROM "ben@example.com,carol@example.com"
$email_header Sender: dave@example.com
As explained in the introduction to RFC6854, an empty From group can also be specified by either of:
$var_def EMAIL_SET FROM "Automated System:;"
$email_header From: "Automated System:;"
