Outdated documentation

You are looking at the documentation for an older release. For the latest information, please see current release documentation.

Postmaster Filters

Pre-sorting standard mail done in a mail room takes care that not every piece of mail sent to the office goes to the same group of people. After a second look at the envelope, rerouting occurs where needed.

OTRS uses so-called postmaster filters to read the email’s envelope and take further action. Depending upon, for example, a subject or sender, an email bound for the service desk could land in a sub-queue or be redirected to a completely different team to create transparency and give your customer the fastest service possible.

Use this screen to add postmaster filters to the system. The postmaster filter management screen is available in the PostMaster Filters module of the Communication & Notifications group.

Postmaster Filter Management Screen

Postmaster Filter Management Screen

Manage Postmaster Filters

Note

When adding or editing a postmaster filter, please keep in mind that they are evaluated in ASCIIbetical order by name.

To add a postmaster filter:

  1. Click on the Add PostMaster Filter button in the left sidebar.
  2. Fill in the required fields.
  3. Click on the Save button.

To edit a postmaster filter:

  1. Click on a postmaster filter in the list of postmaster filters.
  2. Modify the fields.
  3. Click on the Save or Save and finish button.

To delete a postmaster filter:

  1. Click on the trash icon in the list of postmaster filters.
  2. Click on the Confirm button.
Delete Postmaster Filter Screen

Delete Postmaster Filter Screen

Note

If several postmaster filters are added to the system, a filter box is useful to find a particular postmaster filter by just typing to filter.

Warning

The maximum number of 50 postmaster filters should not be exceeded. Exceeding this limit may affect the system performance.

Postmaster Filter Settings

The following settings are available when adding or editing this resource. The fields marked with an asterisk are mandatory.

Postmaster Filter Settings Example

Postmaster Filter Settings Example

Basic Postmaster Filter Settings

Postmaster Filter Settings - Basic

Postmaster Filter Settings - Basic

Name *

The name of this resource. Any type of characters can be entered to this field including uppercase letters and spaces. The name will be displayed in the overview table.

Note

When adding or editing one of the postmaster filters, remember multiple filters may apply to a single mail. Rules are executed and sorted by the ASCII value of the names. Based on the sorted order in the overview, they are applied from top to bottom. Look at the ASCII table to see how to sort your names based on the ASCIIbetical order.

Stop after match *

Postmaster filters are evaluated in ASCIIbetical order. This setting defines the evaluation of the subsequent postmaster filters.

No
All postmaster filters are executed.
Yes
The current postmaster filter is still evaluated, but evaluation of the remaining filters is canceled.

Filter Condition

Postmaster Filter Settings - Filter Condition

Postmaster Filter Settings - Filter Condition

A postmaster filter consists of one or more conditions that must be met in order for the defined actions to be executed on the email. Filter conditions can be defined for specific mail header entries or for strings in the mail body.

Search header field … for value

Select a mail header or an X-OTRS header from the first drop-down list, and enter a value as search term for the selected mail header to the second field. Even regular expressions can be used for extended pattern matching.

A list of mail header entries can be found in RFC5322. It is also possible to define X-OTRS headers as filter condition. The different X-OTRS headers and their meaning are the following:

X-OTRS-AttachmentCount
This contains as value the number of attachments which are contained in the email (e.g. 0 for mails without attachments).
X-OTRS-AttachmentExists
Depending on whether attachments are included in the email this X-OTRS header is set to yes, or it has a no value if no attachments are included.
X-OTRS-BodyDecrypted
If the incoming mail was encrypted, it is possible to add a search term to look for the body of the incoming encrypted mail.
X-OTRS-CustomerNo
Set the customer ID for the ticket.
X-OTRS-CustomerUser
Set the customer user for the ticket.
X-OTRS-DynamicField-<DynamicFieldName>
Saves an additional information value for the ticket on <DynamicFieldName> dynamic field. The possible values depend on dynamic field configuration (e.g. text: Notebook, date: 2010-11-20 00:00:00, integer: 1).
X-OTRS-FollowUp-*
These headers are the same as the ones without the FollowUp prefix, but these headers are applied only for follow-up mails.
X-OTRS-FollowUp-State-Keep
If set to 1, the incoming follow-up message will not change the ticket state. For this purpose the header can be customized in the system configuration using option KeepStateHeader.
X-OTRS-Ignore
If set to Yes or True, the incoming message will completely be ignored and never delivered to the system.
X-OTRS-IsVisibleForCustomer
Controls if the article is shown to customer users. Possible values are 0 or 1.
X-OTRS-Lock
Set the lock state of a ticket. Possible values are lock or unlock.
X-OTRS-Loop
If set to Yes or True, no auto answer is delivered to the sender of the message (mail loop protection).
X-OTRS-Owner
Set the agent as owner for the ticket.
X-OTRS-OwnerID
Set the agent ID as owner for the ticket.
X-OTRS-Priority
Set the priority for the ticket.
X-OTRS-Queue
Defines the queue in which the ticket should be sorted. If a queue is set with this header, this setting has priority over all other filter rules that refer to queues. If you use a sub-queue, specify it as Parent::Sub.
X-OTRS-Responsible
Set the agent as responsible for the ticket.
X-OTRS-ResponsibleID
Set the agent ID as responsible for the ticket.
X-OTRS-SenderType
Set the sender type for the ticket. Possible values are agent, system or customer.
X-OTRS-Service
Set the service for the ticket. If you use a sub-service, specify it as Parent::Sub.
X-OTRS-SLA
Set the service level agreement for the ticket.
X-OTRS-State
Set the state for the ticket.
X-OTRS-State-PendingTime

Set the pending time for the ticket (you should sent a pending state via X-OTRS-State). You can specify absolute dates like 2010-11-20 00:00:00 or relative dates, based on the arrival time of the email. Use the form + $Number $Unit, where $Unit can be s (seconds), m (minutes), h (hours) or d (days). Only one unit can be specified. Examples of valid settings: +50s (pending in 50 seconds), +30m (30 minutes), +12d (12 days).

Note

Settings like +1d 12h are not possible. You can specify +36h instead.

X-OTRS-Title
Set the title for the ticket.
X-OTRS-Type
Set the type for the ticket.

Warning

These headers must be manually injected into the mail by means not provided for by OTRS. OTRS only accepts X-OTRS headers from trusted sources.

See also

The Mail Account Settings defines the trust level.

Negate
If checked, the condition will use the negate search term.

Set Email Headers

Postmaster Filter Settings - Set Email Headers

Postmaster Filter Settings - Set Email Headers

In this section you can choose the actions that are triggered if the filter rules match.

Set email header … with value

Select an X-OTRS header from the first drop-down list, and add a value to the second field that should be set as value of the selected X-OTRS header.

See also

The X-OTRS headers are already described above.

Filter Modules

OTRS provides a set of postmaster filter modules, that processes incoming email messages before they result in ticket articles and might perform actions during the communication flow. The filter modules are located in Kernel/System/PostMaster/Filter/ and can be configured with system configuration options in most of the cases.

See also

The majority of the configuration settings are below the name space PostMaster::PreFilterModule. Please see the configuration reference documentation for more information.

Follow-up Article Visibility Check

The postmaster filter module FollowUpArticleVisibilityCheck (located in Kernel/System/PostMaster/Filter/FollowUpArticleVisibilityCheck.pm) checks, if arrived emails should be marked as internal messages. If the email matches certain criteria, the filter module is able to set email headers about IsVisibleForCustomer status (X-OTRS-IsVisibleForCustomer) and SenderType (X-OTRS-SenderType) for further processing.

To give an overview about how OTRS detects and handles the visibility of incoming emails to related ticket customers, enclosed a summary, that describes how such messages are processed.

If an email message arrives at the OTRS system, the following circumstances will lead to an article, that is visible to the ticket customer user:

  • The message cannot be detected as a follow-up and will lead to a new ticket.
  • The SenderType was set to another value, than customer (maybe through a postmaster filter using header X-OTRS-FollowUp-SenderType, or the sender type is system because of notifications).
  • The customer visibility was explicitly set to a positive value, with an email header X-OTRS-FollowUp-IsVisibleForCustomer.
  • The ticket customer itself is the sender of the message.
  • The sender is external and its SenderType is detected as customer, but did not have any correspondence yet (no email reference in any article of the particular ticket). This happens, when the From field is an unknown email address, that was not a recipient address before (i.e. used within a previous outbound email).