Actions Defined

The following actions are available from the Execute actions and rules drop-down lists available in the PureMessage Manager's Policy Constructor.

Note
As of PureMessage 5.2.1, some actions allow you to specify Japanese characters. See the version 5.2.1 section of the Release History for details.

Accept the message

Deliver the message to its envelope recipients.

Add banner

Add a custom banner to the body or header of a message. If the message contains both an HTML and a plain text part, the banner is added to both (unless Ignore these content-types is used). If the message contains multiple text parts, the banner will be added to the first one.

  • Append banner to message body: Add the banner to the end of the message body. For HTML parts, the banner is inserted just before the </BODY> tag. If there is no </BODY> tag, the banner is inserted just before the </HTML> tag.
  • Prepend banner to message body: Insert the banner at the beginning of the message body. For HTML parts, the banner is inserted immediately after the <BODY> tag. If there is no <BODY> tag, the banner is inserted immediately after the <HTML> tag.
    Note
    Choose either Append banner to message body or Prepend banner to message body, not both.
  • Banner character set: Specify the character set of the banner so it is only added to matching message parts. This field can be a string or a regular expression that matches several aliases of a particular character set. The test is not case sensitive. For example, "Big[_-]5.*" would match and add a banner to message parts declared as "big5", "Big-5", and "BIG5-HKSCS". If a character set is not specified, the banner text is added to all message parts. If the specified character set does not match any message parts, then no banner is added.
  • Add banner to specified header: Add the banner to a message header; specify the header name.
  • Re-code header containing encoded word(s): If a header contains encoded words, re-encode it when adding the banner. This option should be used if adding the banner garbles the original encoded header when prepending text.
  • Ignore these content-types: Ignore a content-type. For example, to add banners to text/plain parts only, specify "text/html".
  • Enclose banner in HTML <PRE> tags: When adding the banner to an HTML part, put the banner in HTML <PRE> tags. This preserves text formatting (for example, newlines and indentation) that would otherwise be lost in the rendered HTML.
  • Data Type: Specify whether the text entered in the File or String field is a string ("Verbatim"), or a filename ("Filename").
  • File or String: If "Verbatim" was specified in the Data Type field, enter the text of the banner in this field (ASCII or Latin1 only). If Filename was specified in the Data Type field, specify the full path and filename. The contents of the file must be text. The file must be of the same charset specified in the policy action.
    Note
    If the banner is specified as verbatim and charset is used, it will only be added successfully if:
    • iconv is enabled in utf8.conf
    • charset is one of:
      • UTF-8
      • iso-2022-jp
      • euc-jp
      • Shift-JIS
      • iso-8859-1
    Conversion from UTF-8 to iso-2022 does not work correctly for older versions of iconv. To work around this limitation, use an iso-2022-jp file for adding the banner.

Add header

Add a header to the message. Specify the name of the header, then the value the header should contain.

Use template variables to specify the value(s) to display in the message header.

Add recipient(s)

Adds a CC (carbon copy) recipient to the message, as opposed to "Redirect the message" (which replaces the envelope recipients) and "Forward to" (which adds a blind carbon copy recipient).

  • Recipient Address: Specify the recipient address. To specify multiple recipients, enclose each recipient's address in quotation marks, and separate them with commas.

Archive message to a file (Extended Policy Model)

A copy of the message is stored in "mbox" format (compatible with many mail readers) in the specified directory and filename.

  • Original Message (No Modifications): When selected, the original, unmodified message is archived. If this option is not specified, PureMessage includes all modifications made to the message up to that point in the policy script.
  • Archive the message to a 'message store' directory: When selected, the message is saved using the PureMessage "message store" directory and file architecture. If a message store does not already exist, it is created in the location specified in the File Name text box (described below). For more about the 'message store', see the pmx_archive section of thepmx-policy man page.
  • File Name: The path to the archive file. If the file already exists, it is overwritten. Any text that appears following the final forward slash (/) is interpreted as the filename. If an absolute path is not specified, the path is interpreted as relative to the home directory of the PureMessage user (/opt/pmx6/home). You must specify a path or filename.

Clean the message of any viruses

Tells the virus engine to clean the virus from the message. If cleaning fails, the message is quarantined, and a message is sent to the recipient based on the specified Failure Template File.

Clean the message of any viruses. All installed engines capable of cleaning will be used to attempt to clean viruses from the message. After cleaning, the message is rescanned to ensure that the clean was successful. If the virus engines are not able to clean the message, the part containing the virus is replaced by data from the specified Failure Template File.

  • Failure Template File: Specify cantclean.tmpl, which is the default template failure file. If you create a custom template file, put it in the appropriate language-specific /opt/pmx6/etc/templates/<language>/virus.d directory or specify a full path.

Collect attachment statistics in message log

Writes an entry in the message log that includes:

  • attachment name
  • attachment type
  • attachment size
  • number of attachments

Copy the message to quarantine

Store a copy of the message in the quarantine. This command does not affect the delivery of the message. If called multiple times, multiple copies of the message are stored in the quarantine. The copy stored in the quarantine incorporates any changes made to the message as a result of actions that have occurred to that point.

  • Quarantine Reason: Specify the reason for quarantine.

Custom policy mark

Mark the message with a key-value pair. This action should only be used for custom policy reports. For more information, see "Viewing and Managing Reports" in the Admimistrative Groups section of the Adminstrator's Reference. The message will accumulate marks as it is processed that are written to the message log. These marks can be used to generate custom statistical reports.

  • Log only one mark per message for the specified key: When selected, PureMessage adds a single mark to the message log per message, for any given key. Regardless of the number of actions associated with the key, only one mark is logged.
  • Key: Enter the key for the mark.
  • Value: Enter the value to associate with the key.

Delete header

Delete the specified header.

  • Header Name: Specify the name of the header.
  • Index: If the header occurs multiple times in the message, specify which occurrence should be deleted. The first occurrence is "0", the second "1", and so on.

Deliver immediately for

Allows the message to be exempted from further processing for the specified recipients. The "envelope to" address is compared against the list or individual addresses specified in the Arguments dialog box. For example, to exempt a user's email from being checked for spam, create a Deliver immediately for action before the spam rule.

The message will be queued for delivery and delivered when the pmx-queue program is run (pmx-queue is configured as a scheduled job).

  • Except: This reverses the exemption. That is, messages for all matches except those specified below will be exempted from further processing.
  • Match-type: Only the "positive" match types (Contains, Is, Is a member of, Matches and Matches regex) can be specified. For example, the Deliver immediately for action supports the use of a regular expression as a match type for exceptions. When regular expressions are used in policy rule tests or actions, they are not prefixed or suffixed with slashes or braces. However, if you are manually editing the policy script on the command line, you must "escape" backslashes and quotes within regular expressions by preceding them with a backslash. (The PureMessage Manager automatically escapes these characters.) See the "Regular Expression Primer " for more information on using regular expressions within the PureMessage policy.
  • Key-list: Enter a list ID or one or more email addresses in this field. To specify multiple addresses, enclose each address in quotation marks, and separate them with commas.

Discard the message

Tells the mail transfer agent to discard the message.

Drop attachment

Discard the attachment, but deliver the message. This action can only be used with tests that check message attachment characteristics. If the message has multiple attachments, the attachment associated with the test will be dropped.

Forward to

Forward message (via a blind carbon copy) to the specified addresses. This action writes a copy of the message to the outgoing queue, which is then delivered.

  • Address: Specify the address. To specify multiple recipients, enclose each address in quotation marks, and separate them with commas.

Log the message with key/value pair

Mark the message with a key-value pair. The message will accumulate "marks" as it is processed that are written to the message log when the message stops processing. These marks can be used to generate Policy Mark Hits reports, which show a count of keywords and keys from the message log.

  • Key: Enter the key for the mark.
  • Value: Enter the value to be attached to the key.

Log the message with keyword

Mark the message with given key. The message will accumulate "marks" as it is processed that are written to the message log when the message stops processing. These marks can be used to generate Policy Mark Hits reports, which show a count of keywords and keys from the message log. The keyword string can consist of alphanumeric characters and underscores, up to a maximum of 64 characters.

  • Key: Enter the key value.

Map recipients

Maps the envelope recipients against the specified address map. The envelope recipients are looked up in the address map; if they match a source address, they are replaced with the destination address defined in the address map.

Note that address maps can be configured with an empty Map To value, which has the result of deleting the message.

  • Map ID: Specify the ID code for the desired map.

Notify

Send a notification email to the sender or recipients of a message. The following fields can be configured for notifications:

  • Notify who?: Specify whether to send the notification to the recipients or the sender of the message.
  • Data Type: Specify whether the text entered in the Notification data field is a string ("Verbatim"), or a filename ("Filename").
  • Map: To map the addresses specified in the Notify who? field against an address map, check the box and enter the desired map ID.
  • Notification Data: If "Verbatim" was specified in the Data Type field, enter the text of the notification in this field. If "Filename" was specified in the Data Type field, specify the full path and filename. The contents of the file must be plain text.

Quarantine the message

Copy the message to the quarantine; do not deliver the message to the intended recipient(s).

  • Reason: Enter the reason for the quarantine.

Redirect the message

Replaces all the envelope recipient addresses with the specified address.

  • Address: Enter the desired address. To specify multiple addresses, enclose each address in quotation marks, and separate them with commas.

Reject the message

Tells the mail transfer agent to reject the message.

  • SMTP Return Code: Optionally, enter a SMTP return code parameter for MTA response. The default is 550.
  • ESMTP Status / Error Code: Optionally, enter an Extended SMTP status/error code for MTA response.
  • Reason: Specify a reason for the rejection. Senders then receive a reason when a message 'bounces' back to them.

Rename attachment

Rename an attachment. The replacement string can use the %%ATTACHMENT_NAME%% template variable to provide the original filename in the replacement name (for example, %%ATTACHMENT_NAME%%.warning)

Replace header

Replace the value of the specified header with the specified value. See the Add header action for a list of template variables that can be used for the value. If the header does not exist, this action will add it.

  • Index: If the header occurs multiple times in the message, specify which occurrence should be deleted. The first occurrence is "0", the second "1", and so on.
  • Header Name: Specify the header name.
  • Header Value: Specify the new value for the header. If no value is specified, the header will not be removed; it will simply have no value.

Replace message part

Replace an attachment, or the whole body of the message, with custom text or a file. If used in the same rule as an attachment test, the matching attachment(s) will be replaced. If it is used outside of this context, the entire body of the message will be replaced.

  • New Body Content-Type: Specify the content-type to use in the replaced part. The default is "text/plain".
  • New Body Transfer-Encoding: Specify the transfer encoding to use in the replaced part. The default is "7bit". Supported transfer encodings: UTF-8, 7bit, 8bit, base64, quoted-printable, binary.
  • Data Type: Specify whether the text entered in the File or String field is a string ("Verbatim"), or a filename ("Filename").
  • File or String: If "Verbatim" was specified in the Data Type field, enter the text of the notification in this field. If "Filename" was specified in the Data Type field, specify the full path and filename. The contents of the file must match the specified body content type.

The following template variables can be used in the file or string.

  • %%ATTACHMENT_NAME%%: The filename of the attachment (as given by the Content-Disposition header)
  • %%ATTACHMENT_TYPE%%: The content-type of the attachment (as given by the Content-Type header)
  • %%ATTACHMENT_SIZE%%: The size of the attachment

Route message

Route the message to a specified server or to multiple servers, usually for the purpose of archiving or encrypting. Enter the IP address(es) or fully qualified hostname(s) of the server(s) to which the message should be routed. For example, you may want make a copy of each message sent to the customer service department and archive it on a separate server.

  • Server(s): Enter the IP address(es) or fully qualified hostname(s) of the "route to" server(s).
  • Route a copy of the message: In addition to processing the message and sending it to its intended destination, a copy of the message is also sent to the specified server(s). If this option is not used, the message will be routed to the specified server instead of the intended recipient(s).
  • Disable bounces: If the specified routing server is not available, do not bounce the message. By default, the message is bounced to the original sender. The original sender receives a notification that is defined in the template /opt/pmx6/etc/templates/Language_Dir/bounce-on-failure.tmpl.
Important
When using the "Route message" action, make sure that the relay you specify here is not also a mail server that is delivering mail via the same server that performed the routing action. This would cause PureMessage to route mail in a continuous loop instead of delivering it.
Note

If, when upgrading to the latest version of PureMessage, an error message is displayed regarding the smtp_generic_maps setting in /opt/pmx6/postfix/etc/main.cf, complete the following steps:

  1. Because policy routing only works with "pcre" maps, ensure that the smtp_generic_maps setting is of the type pcre. For example:

    smtp_generic_maps=pcre:PathToMapFile
  2. In the pcre map file, add the following regular expression on a separate line at the end of the file:
    /(.*)%(.*)@.*/  $1@$2
  3. As the root user, in /opt/pmx6/postfix/etc, run make.

These steps may also be necessary if you are using an external Postfix installation. Follow the same instructions, making adjustments for the different file locations.

Set a template variable

Initialize a template variable with a shell command. This action will execute the shell command and put the output in a template variable that can be used in subsequent tests and actions. Use the %%MESSAGE_FILE%% template in the shell command to determine the filename of a file containing a message.

  • Variable: Specify the template variable name. Can only consist of upper-case alphanumeric characters and underscores.
  • Shell Command: Specify the shell command to run.

Sign message with DKIM header

DomainKeys Identified Mail (DKIM) is an authentication framework used to sign and validate a message, based on the domain of its sender. This action signs outgoing messages with a unique DKIM signature. To configure PureMessage to detect and verify DKIM signatures for incoming messages, see Verify message DKIM header in the "Message Characteristics" section.

In order for this action to take effect, you must configure /opt/pmx6/etc/dkim.conf. This configuration file contains the required signing options, and the location of the private key that is used to create the DKIM signature. If you want multiple PureMessage servers in the same domain to share one signature for the delivery of mail, you must also add the location of the private key to the DomainKeys-Identified-Mail publication. For configuration instructions, see the dkim.conf man page, and "Managing Publications " in the Server Groups Tab section of the Manager Reference .

DKIM signatures depend on access to a private key. This must also be configured in order for the action to take affect. For general information, see www.dkim.org.

The action appends a signature to messages, and, therefore, should only be applied to rules in the "Mail from internal hosts" section of the PureMessage policy.

Stop processing

When you add this action to a rule, it prevents processing of subsequent rules if that rule is hit. If you create a new rule by clicking add rule or Add Alternative, the Stop processing action is added by default.

Tempfail the message

Signal the MTA to return SMTP error code 421 (service not available).

Write an entry to pmx_log

Log a message to the PureMessage log file (as specified by the 'log_to' parameter in the pmx.conf configuration file).

  • Priority String: Enter the priority of the log entry. The following strings can be used: DEBUG, INFO, NOTICE, WARNING, ERR, CRIT, ALERT, EMERG.
  • Message String: Enter the text of the message to be logged.

Write test data to message log

This action is used for policy tests. When tests are run, this action writes a marker to the message log, and uses that marker to track the test message's progress through the policy filter. This action must be defined in the policy in order to run policy tests.