7.2. Receiving emails

7.2.1. Via POP3 accounts - the easy way (PostMasterPOP3.pl)

OTRS is able to receive emails from POP3 accounts.

Configure your POP3 accounts via the admin interface (POP3 Account).

If a new POP3 account is created then its POP3 server, username and password must be specified. If you select "Yes" for "Trusted", the X-OTRS headers are evaluated and executed if such headers are in the incoming message. Because the X-OTRS header can execute some actions in the ticket system you should only set "Trusted" to "Yes" for known senders. X-OTRS-Headers are used by the filter module in OTRS. The X-OTRS headers are explained in this table in more detailed. If you have created filter rules they are executed and used even if "Trusted" is set to "Yes".

The distribution of incoming messages can be controled if they need to be sorted by queue or by the content of the To: field. If "Dispatching by selected queue" is selected for "Dispatching", all incomming messages will be sorted into the specified queue. The address where the mail was sent to doesn't matter. If "Dispatching by email To: field" was selected for "Dispatching", the system checks if a queue is linked with the address in the To: field of the incoming mail. A address can be linked in the mailaddress management section of the admin area. If the address in the To field is linked with a queue, the new message will be sorted into the linked queue. If no link is found between the address in the To: field and queue then the message is sorted into the "Raw" queue in the system, which is the PostmasterDefaultQueue after a default installation.

All data for the POP3 accounts are saved in the OTRS database. The PostMasterPOP3.pl script, which is located in the bin directory of your OTRS installation, uses the settings in the database and fetches the mail. You can execute ./bin/PostMasterPOP3.pl manually to check if all your POP3 settings are working properly. If you want to fetch your mail automatically every ten minutes, you can use a cron job and the example entries that are available in the file var/cron/postmaster_pop3.dist.

7.2.2. Via command line program and e.g. procmail (PostMaster.pl)

If POP3 can't be used to get the email into OTRS, the command line programm bin/PostMaster.pl might be a solution. bin/PostMaster.pl takes the mail via STDIN and pipes them directly into OTRS. That means email will be shown in your OTRS system if the MDA (mail delivery agent, e.g. procmail) executes bin/PostMaster.pl

To test bin/PostMaster.pl without MDA execute the following command:

linux:/opt/otrs# cd bin
linux:/opt/otrs/bin# cat ../doc/test-email-1.box | ./PostMaster.pl
linux:/opt/otrs/bin#

If the email is shown in the QueueView then your setup is working.

Procmail is a very common e-mail filter in the Linux enviroment. It will be installed on most systems. If not, have a look at the procmail homepage.

To configure procmail for OTRS (requires a procmail configured MTA (e.g. sendmail, postfix, exim or qmail)) use the ~otrs/.procmailrc.dist file and copy it to .procmailrc. Add the following:

SYS_HOME=$HOME
PATH=/bin:/usr/bin:/usr/local/bin
# --
# Pipe all email into the PostMaster process.
# --
:0 :
| $SYS_HOME/bin/PostMaster.pl

All email sent to the local OTRS user will be piped into bin/PostMaster.pl and then shown in your QueueView.

7.2.3. Fetching emails via POP3 or IMAP and fetchmail for PostMaster.pl

In order to get email from your mail server via a POP3 or IMAP mailbox to the OTRS machine/local OTRS account and to procmail use fetchmail.

A working SMTP configuration on the OTRS machine is required.

You can use the .fetchmailrc.dist in the home directory of OTRS and copy it to .fetchmailrc. Modfiy/change it for your needs.

#poll (mailserver) protocol POP3 user (user) password (password) is (localuser)
poll mail.example.com protocol POP3 user joe password mama is otrs

Don't forget to set the .fetchmailrc to 710 ("chmod 710 .fetchmailrc")!

With the .fetchmailrc from the example above, all email will be forwarded to the local OTRS account, if the command fetchmail -a is executed. Set up a cronjob with this command if you want to fetch the mails regularly.

7.2.4. Filtering/dispatching by OTRS/PostMaster modules (for more complex dispatching)

If you use the bin/PostMaster.pl or bin/PostMasterPOP3.pl method, you can insert or modify X-OTRS header entries with the PostMaster filter modules. With the X-OTRS headers the ticket system can execute some actions on incomming mails, sort them into a specific queue, change the priority oder change the customer ID for example. More information about the X-OTRS headers are available in the chapter about adding POP3 accounts in the admin area of OTRS.

There are some default filter modules:

The job name (e.g. $Self->{'PostMaster::PreFilterModule'}->{'JobName'}) needs to be unique!

Kernel::System::PostMaster::Filter::Match is a default module to match on some email header (e.g. From, To, Subject, ...). It can set new email headers (e.g. X-OTRS-Ignore: yes or X-OTRS-Queue: spam) if a filter rule matches. The following example jobs can be inserted in Kernel/Config.pm

    # Job Name: 1-Match
    # (block/ignore all spam email with From: noreply@)
    $Self->{'PostMaster::PreFilterModule'}->{'1-Match'} = {
        Module => 'Kernel::System::PostMaster::Filter::Match',
        Match => {
            From => 'noreply@',
        },
        Set => {
            'X-OTRS-Ignore' => 'yes',
        },
    };
    # Job Name: 2-Match
    # (sort emails with From: sales@example.com and Subject: **ORDER**
    # into queue 'Order')
    $Self->{'PostMaster::PreFilterModule'}->{'2-Match'} = {
        Module => 'Kernel::System::PostMaster::Filter::Match',
        Match => {
            To => 'sales@example.com',
            Subject => '**ORDER**',
        },
        Set => {
            'X-OTRS-Queue' => 'Order',
        },
    };

Kernel::System::PostMaster::Filter::CMD is a default module to pipe the email into an external command. The output is given to STDOUT and if the result is true, then set new email header (e.g. X-OTRS-Ignore: yes or X-OTRS-Queue: spam). The following example can be used in Kernel/Config.pm

    # Job Name: 5-SpamAssassin
    # (SpamAssassin example setup, ignore spam emails)
    $Self->{'PostMaster::PreFilterModule'}->{'5-SpamAssassin'} = {
        Module => 'Kernel::System::PostMaster::Filter::CMD',
        CMD => '/usr/bin/spamassassin | grep -i "X-Spam-Status: yes"',
        Set => {
            'X-OTRS-Ignore' => 'yes',
        },
    };

Of course it's also possible to develop your own PostMaster filter modules.