- MAIL PLUGINS
  - Core plugins
- WRITING PLUGINS
  - Plugin methods
  - Plugin hooks
    - BeforeDecrypt
    - BeforeDecode
    - GetCurrentUser
    - CheckACL
    - HandleAction
- 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 available 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-existent 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.

# SEE ALSO

RT::Interface::Email::Role

← Back to index