<chapter id="procmail">
<title>Dispatching of incoming email</title>

<sect1 id="dispatching_via_otrs">
<title>With OTRS</title>
<para>
OTRS is able to dispatch incoming emails via "To" address. Configurable via admin interface.
</para>

<para>
<emphasis role='bold'>Example</emphasis>
</para>
<para>
Add a new system email address (AdminArea -->> System Email Addresses).
<screenshot>
<screeninfo>add email address</screeninfo>
<graphic srccredit="add email address - screenshot" scale="40" fileref="screenshots/admin-add-email.png"></graphic>
</screenshot>
</para>
<para>
In this case, all incoming emails (with To: support@company.com) will be dispatched to the TEST1 queue. 
</para>
</sect1>

<sect1 id="xheader_otrs_queue">
<title>With procmail (for more complex dispatching)</title>
<para>
Procmail is a very common e-mail filter in the Linux enviroment. It will be probably installed on your system. If not have a look at the <ulink url="http://www.procmail.org/"><citetitle>procmail homepage</citetitle></ulink>.
</para>

<para>
<emphasis role='bold'>The X-OTRS-Queue Mail-Header</emphasis>
</para>
<para>
The X-OTRS-Queue Mail-Header is parsed by OTRS and OTRS will pipe these e-mails direct in this queue. Procmail and fromail can be used to create a powerfull dispatcher tool.
</para>

<para>
<emphasis role='bold'>Examples</emphasis>
</para>
<para>
The following examples are copied from the procmailex man-page. Feel free to have a look into it (actually it is quite a good idea). Of course we changed the wording a bit (to fit it into the queueing idea).
</para>

<para>
Sort out all mail coming from the scuba-dive mailing list into the scuba queue.

<screen>
:0 fhw :
* ^TOscuba
| formail -I "X-OTRS-Queue: scuba"
</screen>

Forward all mail from peter about compilers into the william queue.
<screen>
:0 fhw :
* ^From.*peter
* ^Subject:.*compilers
| formail -I "X-OTRS-Queue: william"
</screen>

And here a last example, the whole .procmailrc. 

<example>
<title>.procmailrc</title>
<screen>
# --
# .procmailrc - procmailrc of the OTRS user
# Copyright (C) 2001-2002 Martin Edenhofer (martin+code at otrs.org)
# --
# $Id: procmail.sgml,v 1.6 2002/09/01 12:09:53 martin Exp $
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see 
# the enclosed file COPYING for license information (GPL). If you 
# did not receive this file, see http://www.gnu.org/licenses/gpl.txt.
# --

SYS_HOME=$HOME

PATH=/bin:/usr/bin:/usr/local/bin
MONTHFOLDER=`date +%Y-%m`
YEARFOLDER=`date +%Y`
LOGFILE=$SYS_HOME/var/log/procmail-$MONTHFOLDER.log
VERBOSE=on

# --
# Remove all X-OTRS Header (allow this only for trusted email)
# e. g. from *@example.com
# --
:0 fhw :
* !^From.*@example.com
| grep -vi '^X-OTRS-'

# --
# Examples for queue presorting.
# --

:0 fhw :
* ^List-Id:.*OpenAntiVirus
| formail -I "X-OTRS-Queue: OpenAntiVirus"

:0 fhw :
* ^Sender:.*example.com
| formail -I "X-OTRS-Queue: example"

:0 fhw :
* TO:.*BUGTRAQ
| formail -I "X-OTRS-Queue: BUGTRAQ"

# --
# Backup of all incoming emails. 
# It's always better to have a backup of all incoming emails!
# --
:0 c :
$SYS_HOME/var/INBOX.Backup.$MONTHFOLDER

# --
# Pipe all email into the PostMaster process.
# --
:0 :
| $SYS_HOME/bin/PostMaster.pl

# --
# spool all the rest (which the PostMaster.pl can't process!) 
# If the database is down or the PostMaster.pl exit was not '0'!
# --
:0 :
$SYS_HOME/var/spool/.

# --
# end of .procmailrc
# --
</screen>
</example>

Please have a look into the procmailex man-page for more examples.
</para>

</sect1>

<sect1 id="xheader_otrs_queue_webform">
<title>Example with procmail and a webform</title>
<para>
This is an example for a webform to generate an email for
OTRS. You will find this perl scrtipt in $OTRS_HOME/scripts/webform.pl
</para>

<para>
You have a Topic, From, Email, Subject and Message field.
</para>

<para>
Change the config settings for the webform:
<screen>
# --
# web form options
# -- 
my $Ident = 'ahfiw2Fw32r230dddl2foeo3r';
# sendmail location and options
my $Sendmail = '/usr/sbin/sendmail -t -i -f ';
# email where the emails of the form will send to
my $OpenTRSEmail = 'otrs-system@example.com';
# topics and dest. queues
my %Topics = (
    # topic => OTRS queue
    'Info' => 'info',
    'Support' => 'support',
    'Bugs' => 'bugs',
    'Sales' => 'sales',
    'Billing' => 'billing',
    'Webmaster' => 'webmaster',
);
</screen>

Take care, that your used $OpenTRSEmail and the used OTRS queues exists in your 
OTRS system.
</para>

<para>
Now, change the OTRS .procmailrc from:
<screen>
# --
# Remove all X-OTRS Header (allow this only for trusted email)
# e. g. from *@example.com
# --
:0 fhw :
* !^From.*@example.com
| grep -vi '^X-OTRS-'
</screen>
to:
<screen>
# --
# Remove all X-OTRS Header (allow this only for trusted email)
# just not emails with "X-OTRS-Ident: ahfiw2Fw32r230dddl2foeo3r" header!
# --
:0 fhw :
* !^X-OTRS-Ident: ahfiw2Fw32r230dddl2foeo3r
| grep -vi '^X-OTRS-'
</screen>
If a email is generated by the webform.pl and sent to the $OpenTRSEmail it will
be dispatched to the topic=>queue.
</para>

</sect1>
</chapter>
