-#!!!PERL!! -w
+#!/usr/bin/perl
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2014 Best Practical Solutions, LLC
+# <sales@bestpractical.com>
+#
+# (Except where explicitly superseded by other copyright notices)
+#
+#
+# LICENSE:
+#
+# This work is made available to you under the terms of Version 2 of
+# the GNU General Public License. A copy of that license should have
+# been provided with this software, but in any event can be snarfed
+# from www.gnu.org.
+#
+# This work is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 or visit their web page on the internet at
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+#
+#
+# CONTRIBUTION SUBMISSION POLICY:
+#
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+#
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions, LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+#
+# END BPS TAGGED BLOCK }}}
+=head1 NAME
+
+rt-mailgate - Mail interface to RT.
+
+=cut
-# $Header: /home/cvs/cvsroot/freeside/rt/bin/rt-mailgate,v 1.1 2002-08-12 06:17:07 ivan Exp $
-# (c) 1996-2001 Jesse Vincent <jesse@fsck.com>
-# This software is redistributable under the terms of the GNU GPL
-
-
-package RT;
use strict;
-use vars qw($VERSION $Handle $Nobody $SystemUser);
+use warnings;
-$VERSION="!!RT_VERSION!!";
+use Getopt::Long;
+my $opts = { };
+GetOptions( $opts, "queue=s", "action=s", "url=s",
+ "jar=s", "help", "debug", "extension=s",
+ "timeout=i", "verify-ssl!", "ca-file=s",
+ );
-use lib "!!RT_LIB_PATH!!";
-use lib "!!RT_ETC_PATH!!";
+my $gateway = RT::Client::MailGateway->new();
-use RT::Interface::Email qw(CleanEnv LoadConfig DBConnect
- GetCurrentUser
- GetMessageContent
- CheckForLoops
- CheckForSuspiciousSender
- CheckForAutoGenerated
- ParseMIMEEntityFromSTDIN
- ParseTicketId
- MailError
- ParseCcAddressesFromHead
- ParseSenderAddressFromHead
- ParseErrorsToAddressFromHead
- );
+$gateway->run($opts);
-#Clean out all the nasties from the environment
-CleanEnv();
+package RT::Client::MailGateway;
-#Load etc/config.pm and drop privs
-LoadConfig();
+use LWP::UserAgent;
+use HTTP::Request::Common qw($DYNAMIC_FILE_UPLOAD);
+use File::Temp qw(tempfile tempdir);
+$DYNAMIC_FILE_UPLOAD = 1;
-#Connect to the database and get RT::SystemUser and RT::Nobody loaded
-DBConnect();
+use constant EX_TEMPFAIL => 75;
+use constant BUFFER_SIZE => 8192;
-#Drop setgid permissions
-RT::DropSetGIDPermissions();
+sub new {
+ my $class = shift;
+ my $self = bless {}, $class;
+ return $self;
+}
-use RT::Ticket;
-use RT::Queue;
-use MIME::Parser;
-use File::Temp;
-use Mail::Address;
+sub run {
+ my $self = shift;
+ my $opts = shift;
+ if ( $opts->{running_in_test_harness} ) {
+ $self->{running_in_test_harness} = 1;
+ }
-#Set some sensible defaults
-my $Queue = 1;
-my $time = time;
-my $Action = "correspond";
+ $self->validate_cli_flags($opts);
-my ($Verbose, $ReturnTid, $Debug);
-my ($From, $TicketId, $Subject,$SquelchReplies);
+ my $ua = $self->get_useragent($opts);
+ my $post_params = $self->setup_session($opts);
+ $self->upload_message( $ua => $post_params );
+ $self->exit_with_success();
+}
-# using --owner-from-extension, this will let you set ticket owner on create
-my $AssignTicketTo = undef;
-my ($status, $msg);
+sub exit_with_success {
+ my $self = shift;
+ if ( $self->{running_in_test_harness} ) {
+ return 1;
+ } else {
+ exit 0;
+ }
+}
-# {{{ parse commandline
+sub tempfail {
+ my $self = shift;
+ if ( $self->{running_in_test_harness} ) {
+ die "tempfail";
+ } else {
-while (my $flag = shift @ARGV) {
- if (($flag eq '-v') or ($flag eq '--verbose')) {
- $Verbose = 1;
+ exit EX_TEMPFAIL;
}
- if (($flag eq '-t') or ($flag eq '--ticketid')) {
- $ReturnTid = 1;
+}
+
+sub permfail {
+ my $self = shift;
+ if ( $self->{running_in_test_harness} ) {
+ die "permfail";
+ } else {
+
+ exit 1;
}
-
- if (($flag eq '-d') or ($flag eq '--debug')) {
- $RT::Logger->debug("Debug mode enabled\n");
- $Debug = 1;
- }
-
- if (($flag eq '-q') or ($flag eq '--queue')) {
- $Queue = shift @ARGV;
- }
- if ($flag eq '--ticket-id-from-extension') {
- $TicketId = $ENV{'EXTENSION'};
+}
+
+sub validate_cli_flags {
+ my $self = shift;
+ my $opts = shift;
+ if ( $opts->{'help'} ) {
+ require Pod::Usage;
+ Pod::Usage::pod2usage( { verbose => 2 } );
+ return $self->permfail()
+ ; # Don't want to succeed if this is really an email!
}
- if ($flag eq '--queue-from-extension') {
- $Queue = $ENV{'EXTENSION'};
+
+ unless ( $opts->{'url'} ) {
+ print STDERR
+ "$0 invoked improperly\n\nNo 'url' provided to mail gateway!\n";
+ return $self->permfail();
}
- if ($flag eq '--owner-from-extension') {
- $AssignTicketTo = $ENV{'EXTENSION'};
+
+ if (($opts->{'ca-file'} or $opts->{"verify-ssl"})
+ and not LWP::UserAgent->can("ssl_opts")) {
+ print STDERR "Verifying SSL certificates requires LWP::UserAgent 6.0 or higher.\n";
+ return $self->tempfail();
}
- if (($flag eq '-a') or ($flag eq '--action')) {
- $Action = shift @ARGV;
- }
-
-
+ $opts->{"verify-ssl"} = 1 unless defined $opts->{"verify-ssl"};
}
-# }}}
+sub get_useragent {
+ my $self = shift;
+ my $opts = shift;
+ my $ua = LWP::UserAgent->new();
+ $ua->cookie_jar( { file => $opts->{'jar'} } ) if $opts->{'jar'};
-# get the current mime entity from stdin
-my ($entity, $head) = ParseMIMEEntityFromSTDIN();
+ if ( $ua->can("ssl_opts") ) {
+ $ua->ssl_opts( verify_hostname => $opts->{'verify-ssl'} );
+ $ua->ssl_opts( SSL_ca_file => $opts->{'ca-file'} )
+ if $opts->{'ca-file'};
+ }
-#Get someone to send runtime errors to;
-my $ErrorsTo = ParseErrorsToAddressFromHead($head);
+ return $ua;
+}
-#Get us a current user object.
-my $CurrentUser = GetCurrentUser($head, $entity, $ErrorsTo);
+sub setup_session {
+ my $self = shift;
+ my $opts = shift;
+ my %post_params;
+ foreach (qw(queue action)) {
+ $post_params{$_} = $opts->{$_} if defined $opts->{$_};
+ }
-# We've already performed a warning and sent the mail off to somewhere safe ($RTOwner).
-# this is _exceedingly_ unlikely but we don't want to keep going if we don't have a current user
+ if ( ( $opts->{'extension'} || '' ) =~ /^(?:action|queue|ticket)$/i ) {
+ $post_params{ lc $opts->{'extension'} } = $ENV{'EXTENSION'}
+ || $opts->{ $opts->{'extension'} };
+ } elsif ( $opts->{'extension'} && $ENV{'EXTENSION'} ) {
+ print STDERR
+ "Value of the --extension argument is not action, queue or ticket"
+ . ", but environment variable EXTENSION is also defined. The former is ignored.\n";
+ }
-unless ($CurrentUser->Id) {
- exit(1);
-}
+ # add ENV{'EXTENSION'} as X-RT-MailExtension to the message header
+ if ( my $value = ( $ENV{'EXTENSION'} || $opts->{'extension'} ) ) {
-my $MessageId = $head->get('Message-Id') ||
- "<no-message-id-".time.rand(2000)."\@.$RT::Organization>";
+ # prepare value to avoid MIME format breakage
+ # strip trailing newline symbols
+ $value =~ s/(\r*\n)+$//;
-#Pull apart the subject line
-$Subject = $head->get('Subject') || "[no subject]";
-chomp $Subject;
+ # make a correct multiline header field,
+ # with tabs in the beginning of each line
+ $value =~ s/(\r*\n)/$1\t/g;
+ $opts->{'headers'} .= "X-RT-Mail-Extension: $value\n";
+ }
+
+ # Read the message in from STDIN
+ # _raw_message is used for testing
+ my $message = $opts->{'_raw_message'} || $self->slurp_message();
+ unless ( $message->{'filename'} ) {
+ $post_params{'message'} = [
+ undef, '',
+ 'Content-Type' => 'application/octet-stream',
+ Content => ${ $message->{'content'} },
+ ];
+ } else {
+ $post_params{'message'} = [
+ $message->{'filename'}, '',
+ 'Content-Type' => 'application/octet-stream',
+ ];
+ }
-# Get the ticket ID unless it's already set
-$TicketId = ParseTicketId($Subject) unless ($TicketId);
+ return \%post_params;
+}
-#Set up a queue object
-my $QueueObj = RT::Queue->new($CurrentUser);
-$QueueObj->Load($Queue);
-unless ($QueueObj->id ) {
+sub upload_message {
+ my $self = shift;
+ my $ua = shift;
+ my $post_params = shift;
+ my $full_url = $opts->{'url'} . "/REST/1.0/NoAuth/mail-gateway";
+ print STDERR "$0: connecting to $full_url\n" if $opts->{'debug'};
- MailError(To => $RT::OwnerEmail,
- Subject => "RT Bounce: $Subject",
- Explanation => "RT couldn't find the queue: $Queue",
- MIMEObj => $entity);
+ $ua->timeout( exists( $opts->{'timeout'} ) ? $opts->{'timeout'} : 180 );
+ my $r = $ua->post( $full_url, $post_params, Content_Type => 'form-data' );
+ $self->check_failure($r);
-}
+ my $content = $r->content;
+ print STDERR $content . "\n" if $opts->{'debug'};
-# {{{ Lets check for mail loops of various sorts.
+ return if ( $content =~ /^(ok|not ok)/ );
-my $IsAutoGenerated = CheckForAutoGenerated($head);
+ # It's not the server's fault if the mail is bogus. We just want to know that
+ # *something* came out of the server.
+ print STDERR <<EOF;
+RT server error.
-my $IsSuspiciousSender = CheckForSuspiciousSender($head);
+The RT server which handled your email did not behave as expected. It
+said:
-my $IsALoop = CheckForLoops($head);
+$content
+EOF
+ return $self->tempfail();
+}
-#If the message is autogenerated, we need to know, so we can not
-# send mail to the sender
-if ($IsSuspiciousSender || $IsAutoGenerated || $IsALoop) {
- $SquelchReplies = 1;
+sub check_failure {
+ my $self = shift;
+ my $r = shift;
+ return if $r->is_success;
- $ErrorsTo = $RT::OwnerEmail;
-
- #TODO: Is what we want to do here really
- # "Make the requestor cease to get mail from RT"?
- # This might wreak havoc with vacation-mailing users.
- # Maybe have a "disabled for bouncing" state that gets
- # turned off when we get a legit incoming message
+ # XXX TODO 4.2: Remove the multi-line error strings in favor of something more concise
+ print STDERR <<" ERROR";
+An Error Occurred
+=================
+@{[ $r->status_line ]}
+ ERROR
+ print STDERR "\n$0: undefined server error\n" if $opts->{'debug'};
+ return $self->tempfail();
}
+sub slurp_message {
+ my $self = shift;
+
+ local $@;
+
+ my %message;
+ my ( $fh, $filename )
+ = eval { tempfile( DIR => tempdir( CLEANUP => 1 ) ) };
+ if ( !$fh || $@ ) {
+ print STDERR "$0: Couldn't create temp file, using memory\n";
+ print STDERR "error: $@\n" if $@;
+
+ my $message = \do { local ( @ARGV, $/ ); <STDIN> };
+ unless ( $$message =~ /\S/ ) {
+ print STDERR "$0: no message passed on STDIN\n";
+ $self->exit_with_success;
+ }
+ $$message = $opts->{'headers'} . $$message if $opts->{'headers'};
+ return ( { content => $message } );
+ }
+
+ binmode $fh;
+ binmode \*STDIN;
+
+ print $fh $opts->{'headers'} if $opts->{'headers'};
+
+ my $buf;
+ my $empty = 1;
+ while (1) {
+ my $status = read \*STDIN, $buf, BUFFER_SIZE;
+ unless ( defined $status ) {
+ print STDERR "$0: couldn't read message: $!\n";
+ return $self->tempfail();
+ } elsif ( !$status ) {
+ last;
+ }
+ $empty = 0 if $buf =~ /\S/;
+ print $fh $buf;
+ }
+ close $fh;
-# {{{ Warn someone if it's a loop
-
-# Warn someone if it's a loop, before we drop it on the ground
-if ($IsALoop) {
- $RT::Logger->crit("RT Received mail ($MessageId) from itself.");
-
- #Should we mail it to RTOwner?
- if ($RT::LoopsToRTOwner) {
- MailError(To => $RT::OwnerEmail,
- Subject => "RT Bounce: $Subject",
- Explanation => "RT thinks this message may be a bounce",
- MIMEObj => $entity);
-
- #Do we actually want to store it?
- exit unless ($RT::StoreLoops);
+ if ($empty) {
+ print STDERR "$0: no message passed on STDIN\n";
+ $self->exit_with_success;
}
+ print STDERR "$0: temp file is '$filename'\n" if $opts->{'debug'};
+ return ( { filename => $filename } );
}
-# }}}
+=head1 SYNOPSIS
+ rt-mailgate --help : this text
- #Don't let the user stuff the RT-Squelch-Replies-To header.
- if ($head->get('RT-Squelch-Replies-To')) {
- $head->add('RT-Relocated-Squelch-Replies-To',
- $head->get('RT-Squelch-Replies-To'));
- $head->delete('RT-Squelch-Replies-To')
- }
+Usual invocation (from MTA):
+ rt-mailgate --action (correspond|comment|...) --queue queuename
+ --url http://your.rt.server/
+ [ --debug ]
+ [ --extension (queue|action|ticket) ]
+ [ --timeout seconds ]
-if ($SquelchReplies) {
- ## TODO: This is a hack. It should be some other way to
- ## indicate that the transaction should be "silent".
- my ($Sender, $junk) = ParseSenderAddressFromHead($head);
- $head->add('RT-Squelch-Replies-To', $Sender);
-}
-# }}}
+=head1 OPTIONS
+=over 3
-# {{{ If we require that the sender be found in an external DB and they're not
-# forward this message to RTOwner
+=item C<--action>
+Specifies what happens to email sent to this alias. The avaliable
+basic actions are: C<correspond>, C<comment>.
-if ($RT::LookupSenderInExternalDatabase &&
- $RT::SenderMustExistInExternalDatabase ) {
+If you've set the RT configuration variable B<< C<UnsafeEmailCommands> >>,
+C<take> and C<resolve> are also available. You can execute two or more
+actions on a single message using a C<-> separated list. RT will execute
+the actions in the listed order. For example you can use C<take-comment>,
+C<correspond-resolve> or C<take-comment-resolve> as actions.
- MailError(To => $RT::OwnerEmail,
- Subject => "RT Bounce: $Subject",
- Explanation => "RT couldn't find requestor via its external database lookup",
- MIMEObj => $entity);
-
-}
+Note that C<take> and C<resolve> actions ignore message text if used
+alone. Include a C<comment> or C<correspond> action if you want RT
+to record the incoming message.
-# }}}
-
-# {{{ elsif we don't have a ticket Id, we're creating a new ticket
-
-
-
-elsif (!defined($TicketId)) {
-
- # {{{ Create a new ticket
- if ($Action =~ /correspond/) {
-
- # open a new ticket
- my @Requestors = ($CurrentUser->id);
-
- my @Cc;
- if ($RT::ParseNewMessageForTicketCcs) {
- @Cc = ParseCcAddressesFromHead(Head => $head,
- CurrentUser => $CurrentUser,
- QueueObj => $QueueObj );
- }
-
- my $Ticket = new RT::Ticket($CurrentUser);
- my ($id, $Transaction, $ErrStr) =
- $Ticket->Create ( Queue => $Queue,
- Subject => $Subject,
- Owner => $AssignTicketTo,
- Requestor => \@Requestors,
- Cc => \@Cc,
- MIMEObj => $entity
- );
- if ($id == 0 ) {
- MailError( To => $ErrorsTo,
- Subject => "Ticket creation failed",
- Explanation => $ErrStr,
- MIMEObj => $entity
- );
- $RT::Logger->error("Create failed: $id / $Transaction / $ErrStr ");
- }
- }
+The default action is C<correspond>.
- # }}}
-
- else {
- #TODO Return an error message
- MailError( To => $ErrorsTo,
- Subject => "No ticket id specified",
- Explanation => "$Action aliases require a TicketId to work on",
- MIMEObj => $entity
- );
-
- $RT::Logger->crit("$Action aliases require a TicketId to work on ".
- "(from ".$CurrentUser->UserObj->EmailAddress.") ".
- $MessageId);
- }
-}
+=item C<--queue>
-# }}}
-
-# {{{ If we've got a ticket ID, update the ticket
-
-else {
-
- # If the action is comment, add a comment.
- if ($Action =~ /comment/i){
-
- my $Ticket = new RT::Ticket($CurrentUser);
- $Ticket->Load($TicketId);
- unless ($Ticket->Id) {
- MailError( To => $ErrorsTo,
- Subject => "Comment not recorded",
- Explanation => "Could not find a ticket with id $TicketId",
- MIMEObj => $entity
- );
- #Return an error message saying that Ticket "#foo" wasn't found.
- }
-
- ($status, $msg) = $Ticket->Comment(MIMEObj=>$entity);
- unless ($status) {
- #Warn the sender that we couldn't actually submit the comment.
- MailError( To => $ErrorsTo,
- Subject => "Comment not recorded",
- Explanation => $msg,
- MIMEObj => $entity
- );
- }
- }
+This flag determines which queue this alias should create a ticket in if no ticket identifier
+is found.
- # If the message is correspondence, add it to the ticket
- elsif ($Action =~ /correspond/i) {
- my $Ticket = RT::Ticket->new($CurrentUser);
- $Ticket->Load($TicketId);
-
- #TODO: Check for error conditions
- ($status, $msg) = $Ticket->Correspond(MIMEObj => $entity);
- unless ($status) {
-
- #Return mail to the sender with an error
- MailError( To => $ErrorsTo,
- Subject => "Correspondence not recorded",
- Explanation => $msg,
- MIMEObj => $entity
- );
- }
- }
+=item C<--url>
- else {
- #Return mail to the sender with an error
- MailError( To => $ErrorsTo,
- Subject => "RT Configuration error",
- Explanation => "'$Action' not a recognized action.".
- " Your RT administrator has misconfigured ".
- "the mail aliases which invoke RT" ,
- MIMEObj => $entity
- );
-
- $RT::Logger->crit("$Action type unknown for $MessageId");
-
- }
-
-}
+This flag tells the mail gateway where it can find your RT server. You should
+probably use the same URL that users use to log into RT.
-# }}}
+If your RT server uses SSL, you will need to install additional Perl
+libraries. RT will detect and install these dependencies if you pass the
+C<--enable-ssl-mailgate> flag to configure as documented in RT's README.
-$RT::Handle->Disconnect();
+If you have a self-signed SSL certificate, you may also need to pass
+C<--ca-file> or C<--no-verify-ssl>, below.
+=item C<--ca-file> I<path>
-# Everything below this line is a helper sub. most of them will eventually
-# move to Interface::Email
+Specifies the path to the public SSL certificate for the certificate
+authority that should be used to verify the website's SSL certificate.
+If your webserver uses a self-signed certificate, you should
+preferentially use this option over C<--no-verify-ssl>, as it will
+ensure that the self-signed certificate that the mailgate is seeing the
+I<right> self-signed certificate.
-#When we call die, trap it and log->crit with the value of the die.
-$SIG{__DIE__} = sub {
- unless ($^S || !defined $^S ) {
- $RT::Logger->crit("$_[0]");
- MailError( To => $ErrorsTo,
- Bcc => $RT::OwnerEmail,
- Subject => "RT Critical error. Message not recorded!",
- Explanation => "$_[0]",
- MIMEObj => $entity
- );
- exit(-1);
- }
- else {
- #Get out of here if we're in an eval
- die $_[0];
- }
-};
+=item C<--no-verify-ssl>
+
+This flag tells the mail gateway to trust all SSL certificates,
+regardless of if their hostname matches the certificate, and regardless
+of CA. This is required if you have a self-signed certificate, or some
+other certificate which is not traceable back to an certificate your
+system ultimitely trusts.
+
+Verifying SSL certificates requires L<LWP::UserAgent> version 6.0 or
+higher; explicitly passing C<--verify-ssl> on prior versions will error.
+
+=item C<--extension> OPTIONAL
+
+Some MTAs will route mail sent to user-foo@host or user+foo@host to user@host
+and present "foo" in the environment variable $EXTENSION. By specifying
+the value "queue" for this parameter, the queue this message should be
+submitted to will be set to the value of $EXTENSION. By specifying
+"ticket", $EXTENSION will be interpreted as the id of the ticket this message
+is related to. "action" will allow the user to specify either "comment" or
+"correspond" in the address extension.
+
+=item C<--debug> OPTIONAL
+
+Print debugging output to standard error
+
+
+=item C<--timeout> OPTIONAL
+
+Configure the timeout for posting the message to the web server. The
+default timeout is 3 minutes (180 seconds).
+
+=back
+
+
+=head1 DESCRIPTION
+
+The RT mail gateway is the primary mechanism for communicating with RT
+via email. This program simply directs the email to the RT web server,
+which handles filing correspondence and sending out any required mail.
+It is designed to be run as part of the mail delivery process, either
+called directly by the MTA or C<procmail>, or in a F<.forward> or
+equivalent.
+
+=head1 SETUP
+
+Much of the set up of the mail gateway depends on your MTA and mail
+routing configuration. However, you will need first of all to create an
+RT user for the mail gateway and assign it a password; this helps to
+ensure that mail coming into the web server did originate from the
+gateway.
+
+Next, you need to route mail to C<rt-mailgate> for the queues you're
+monitoring. For instance, if you're using F</etc/aliases> and you have a
+"bugs" queue, you will want something like this:
+
+ bugs: "|/opt/rt4/bin/rt-mailgate --queue bugs --action correspond
+ --url http://rt.mycorp.com/"
+
+ bugs-comment: "|/opt/rt4/bin/rt-mailgate --queue bugs --action comment
+ --url http://rt.mycorp.com/"
+
+Note that you don't have to run your RT server on your mail server, as
+the mail gateway will happily relay to a different machine.
+
+=head1 CUSTOMIZATION
+
+By default, the mail gateway will accept mail from anyone. However,
+there are situations in which you will want to authenticate users
+before allowing them to communicate with the system. You can do this
+via a plug-in mechanism in the RT configuration.
+
+You can set the array C<@MailPlugins> to be a list of plugins. The
+default plugin, if this is not given, is C<Auth::MailFrom> - that is,
+authentication of the person is done based on the C<From> header of the
+email. If you have additional filters or authentication mechanisms, you
+can list them here and they will be called in order:
+
+ Set( @MailPlugins =>
+ "Filter::SpamAssassin",
+ "Auth::LDAP",
+ # ...
+ );
+
+See the documentation for any additional plugins you have.
+
+You may also put Perl subroutines into the C<@MailPlugins> array, if
+they behave as described below.
+
+=head1 WRITING PLUGINS
+
+What's actually going on in the above is that C<@MailPlugins> is a
+list of Perl modules; RT prepends C<RT::Interface::Email::> to the name,
+to form a package name, and then C<use>'s this module. The module is
+expected to provide a C<GetCurrentUser> subroutine, which takes a hash of
+several parameters:
+
+=over 4
+
+=item Message
+
+A C<MIME::Entity> object representing the email
+
+=item CurrentUser
+
+An C<RT::CurrentUser> object
+
+=item AuthStat
+
+The authentication level returned from the previous plugin.
+
+=item Ticket [OPTIONAL]
+
+The ticket under discussion
+
+=item Queue [OPTIONAL]
+
+If we don't already have a ticket id, we need to know which queue we're talking about
+
+=item Action
+
+The action being performed. At the moment, it's one of "comment" or "correspond"
+
+=back
+
+It returns two values, the new C<RT::CurrentUser> object, and the new
+authentication level. The authentication level can be zero, not allowed
+to communicate with RT at all, (a "permission denied" error is mailed to
+the correspondent) or one, which is the normal mode of operation.
+Additionally, if C<-1> is returned, then the processing of the plug-ins
+stops immediately and the message is ignored.
+
+=head1 ENVIRONMENT
+
+=over 4
+
+=item EXTENSION
+
+Some MTAs will route mail sent to user-foo@host or user+foo@host to user@host
+and present "foo" in the environment variable C<EXTENSION>. Mailgate adds value
+of this variable to message in the C<X-RT-Mail-Extension> field of the message
+header.
+
+See also C<--extension> option. Note that value of the environment variable is
+always added to the message header when it's not empty even if C<--extension>
+option is not provided.
+=back
+=cut
-1;
projects / freeside.git / blobdiff