RT 4.4.3 Documentation

Extending/Mail plugins

MAIL PLUGINS
- Core plugins
WRITING PLUGINS
- Plugin methods
- Plugin hooks
SEE ALSO

MAIL PLUGINS

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 @MailPlugins to be a list of plugins. For example, to allow the mailgate to specify a 'take' action, you can use the bundled RT::Interface::Email::Action::Take:

    Set( @MailPlugins,
        "Action::Take",
    );

Anonymous subroutine references found in @MailPlugins are treated like "GetCurrentUser" methods.

Core plugins

A small number of plugins are included with core RT, but not enabled by default:

RT::Interface::Email::Action::Take: Allows the mailgate to specify --action take-comment, for instance, which would take the ticket before commenting. This action is somewhat "unsafe," which is why it is not enabled by default. It can also often be accomplished via a scrip instead.
RT::Interface::Email::Action::Resolve: Allows the mailgate to specify --action correspond-resolve, for instance, which would correspond, then resolve the ticket. This action is somewhat "unsafe," which is why it is not enabled by default. It can also often be accomplished via a scrip instead.
RT::Interface::Email::Authz::RequireEncrypted: Forces that all incoming mail be encrypted to be accepted.

You may also put Perl subroutines into the @MailPlugins array, if they behave as described below.

WRITING PLUGINS

@MailPlugins is a list of Perl modules; RT prepends RT::Interface::Email:: to the name to form a package name, and then use's this module. The module should implement RT::Interface::Email::Role.

Plugin methods

RT::Interface::Email::Role defines a number of functions which are useful for immediately aborting processing. They include "SUCCESS" in RT::Interface::Email::Role, "FAILURE" in RT::Interface::Email::Role, and "TMPFAIL" in RT::Interface::Email::Role; read their descriptions for information on how to immediately abort processing from mail plugins.

Plugin hooks

Mail plugins are expected to provide one or more of the following methods:

BeforeDecrypt

Called before the message is decoded or decrypted. Its return value is ignored; it is passed the following parameters:

Message: A MIME::Entity object representing the mail. This may be modified by the plugin.
RawMessage: A reference to the string containing the original message. This should not be modified.
Queue: A RT::Queue, the --queue argument which was passed rt-mailgate.
Actions: An array reference of actions to perform; the --action argument which was passed to rt-mailgate. This may be modified.

BeforeDecode

Called after the message has been decrypted and verified, but before the bodies have been decoded of their content transfer encoding. Its return value is ignored; it is passed the following parameters:

Message: A MIME::Entity object representing the mail. This may be modified by the plugin.
RawMessage: A reference to the string containing the original message. This should not be modified.
Queue: A RT::Queue, the --queue argument which was passed rt-mailgate.
Actions: An array reference of actions to perform; the --action argument which was passed to rt-mailgate. This may be modified.

GetCurrentUser

This method is called in order on the mail plugins that define it. The first method to return a RT::CurrentUser value shortcuts all other plugins. It is passed:

Message: A MIME::Entity object representing the mail. This may be modified by the plugin.
RawMessage: A reference to the string containing the original message. This should not be modified.
Ticket: A RT::Ticket, the ticket (if any) that has been extracted from the subject. If there was no ticket id, this value will be a RT::Ticket object with no id.
Queue: A RT::Queue, the --queue argument which was passed rt-mailgate.

CheckACL

Called to determine authorization -- namely, can the current user complete the action in question? While RT's standard permission controls apply, this allows a better error message, or more limited restrictions on the email gateway.

Only the first action (if there are more than one defined) is checked, as the process of completing the first action might affect the later actions; consider the case of take-correspond, where the correspond action might only be avilable to owners.

Each plugin defining this method is called in turn; as soon as one plugin returns true, the rest are short-circuited. Arguments include:

Message: A MIME::Entity object representing the mail. This may be modified by the plugin.
CurrentUser: A RT::CurrentUser object representing the authenticated user.
Action: A string representing the action to be undertaken.
Ticket: A RT::Ticket, the ticket (if any) that has been extracted from the subject. If there was no ticket id, this value will be a RT::Ticket object with no id.
Queue: A RT::Queue, the --queue argument which was passed rt-mailgate.

HandleAction

For any given action foo, the presence of a subroutine called HandleFoo signals the ability of the mailgate to handle that action. The first plugin in to define the method is called, and its return value ignored. It is passed:

Message: A MIME::Entity object representing the mail. This may be modified by the plugin.
Subject: A string, the original Subject header of the message before it was modified to extract the ticket id.
CurrentUser: A RT::CurrentUser object representing the authenticated user.
Ticket: A RT::Ticket, the ticket (if any) that has been extracted from the subject. If there was no ticket id, this value will be a RT::Ticket object with no id.
TicketId: The value id that was extracted from the subject; this allows a non-existant ticket id to be differentiated from no subject id, as both will present as having an unloaded Ticket argument.
Queue: A RT::Queue, the --queue argument which was passed rt-mailgate.