Node:Outgoing email formats, Next:, Previous:Audit-trail formats, Up:dbconfig file


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.