4.3.7 Outgoing email formats

During the life of a PR, gnats can be configured to send out a range of email messages. When a PR first arrives, an acknowledgment message is sent out if the send-submitter-ack parameter above is set to true. Certain edits to the PR may also cause email to be sent out to the various parties, and if a PR is deleted, gnats may send notification email.

The formats of the email messages are controlled by mail-format sections in the dbconfig file. The general structure of a mail-format section is as follows:

     mail-format "format-name" {
       from-address {
         [ fixed-address "address" ]
         [ email-header-name | [ mail-header-name | ... ] ]
       }
       to-address {
         [ fixed-address "address" ]
         [ "email-header-name" | [ "mail-header-name" | ... ] ]
       }
       reply-to {
         [ fixed-address "address" ]
         [ "email-header-name" | ... ] | [ "gnats-field-name" | ... ]
       }
       header {
         format "formatstring"
         [ fields { "fieldname" [ "fieldname" ... ] } ]
       }
       body {
         format "formatstring"
         [ fields { "fieldname" [ "fieldname" ... ] } ]
       }
     }

gnats recognizes and uses 6 different format-name values:

initial-response-to-submitter

Format of the message used when mailing an initial response back to the PR submitter. This message will only be sent if send-submitter-ack in the overall database configuration is set to true.

initial-pr-notification

Format of the message sent to the responsible parties when a new PR with category different from “pending” arrives.

initial-pr-notification-pending

Format of the message sent to the responsible parties when a new PR that ends up with category “pending” arrives.

appended-email-response

Format of the notification message sent out when a response to a PR is received via email.

audit-mail

Format of the message sent out when a PR edit generates an Audit-Trail entry.

deleted-pr-mail

Format of the message sent out when a PR is deleted.

The from-address, to-address and reply-to subsections of a mail-format section specify the contents of the To:, From: and Reply-To: headers in outgoing email. There are two ways to specify the contents: by using a fixed-address specification, or by specifying email-header-names or gnats-field-names.

When an email-header-name or gnats-field-name value is given, gnats will attempt to extract an email address from the specified location. If several values are given on the same line, separated by | characters, gnats will try to extract an address from each location in turn until it finds a header or field which is nonempty. The following example should clarify this:

     mail-format "initial-response-to-submitter" {
       from-address {
         fixed-address "gnats-admin"
       }
       to-addresses {
         "Reply-To:" | "From:" | "Submitter-Id"
       } ...

This partial mail-format section specifies the format of the address headers in the email message that is sent out as an acknowledgment of a received PR. The From: field of the message will contain the email address of the gnats administrator, as specified by the gnats-admin line in the responsible file. To fill in the To: header, gnats will first look for the mail header Reply-To: in the PR and use the contents of that, if any. If that header doesn't exist or is empty, it will look for the contents of the From: email header, and if that yields nothing, it will look for the gnats Submitter-Id field and use the contents of that.

Other email headers to be included in messages sent out by gnats can be specified by header subsections of the mail-header section. formatstring and fieldname are similar to those used by the named query format. Each header line must have a newline character (\n) at the end.

The email message body is specified in the body subsection of the mail-format section. Just as for a header section, the body section must contain a formatstring and fieldname values.

For some of the formats that gnats recognizes, special variables are available for use. The following table lists the formats that provide special variables. See the example below for an illustration of how they are used.

appended-email-response

$MailFrom

The From: line of the original message.

$MailTo

The To: line of the original message.

$MailSubject

The Subject: line of the original message.

$MailCC

The CC: line of the original message.

$NewAuditTrail

The text of the new audit trail entry (corresponds to the body of the message).

audit-mail

$EditUserEmailAddr

The email address of the user editing the PR. Set by the EDITADDR gnatsd command or from the responsible file; if not available, user's local address is used.

$OldResponsible

The previous Responsible field entry, if it was changed.

$NewAuditTrail

The Audit-Trail: entries that have been appended by the edits.

deleted-pr-mail

$EditUserEmailAddr

The email address of the user deleting the PR. Set by the EDITADDR gnatsd command or from the responsible file; if not available, user's local address is used.

$PRNum

The number of the PR that was deleted.

The following example illustrates the use of these special variables:

     mail-format "deleted-pr-mail" {
       from-address {
         "$EditUserEmailAddr"
       }
       to-addresses {
         fixed-address "gnats-admin"
       }
       header {
         format "Subject: Deleted PR %s\n"
         fields { "$PRNum" }
       }
       body {
         format "PR %s was deleted by user %s.\n"
         fields { "$PRNum" "$EditUserEmailAddr" }
       }
     }

This mail-format section specifies the format of the email message that is sent out when a PR is deleted. The From: field is set to the email address field of the user who deleted the PR, the subject of the message contains the number of the deleted PR, and the message body contains both the PR number and the user's email address.