1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
=head1 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 C<@MailPlugins> to be a list of plugins. For
example, to allow the mailgate to specify a 'take' action, you can use
the bundled L<RT::Interface::Email::Action::Take>:
Set( @MailPlugins,
"Action::Take",
);
Anonymous subroutine references found in C<@MailPlugins> are treated
like L</GetCurrentUser> methods.
=head2 Core plugins
A small number of plugins are included with core RT, but not enabled by
default:
=over
=item L<RT::Interface::Email::Action::Take>
Allows the mailgate to specify C<--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.
=item L<RT::Interface::Email::Action::Resolve>
Allows the mailgate to specify C<--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.
=item L<RT::Interface::Email::Authz::RequireEncrypted>
Forces that all incoming mail be encrypted to be accepted.
=back
You may also put Perl subroutines into the C<@MailPlugins> array, if
they behave as described below.
=head1 WRITING PLUGINS
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 should implement
L<RT::Interface::Email::Role>.
=head2 Plugin methods
L<RT::Interface::Email::Role> defines a number of functions which are
useful for immediately aborting processing. They include
L<RT::Interface::Email::Role/SUCCESS>,
L<RT::Interface::Email::Role/FAILURE>, and
L<RT::Interface::Email::Role/TMPFAIL>; read their descriptions for
information on how to immediately abort processing from mail plugins.
=head2 Plugin hooks
Mail plugins are expected to provide one or more of the following
methods:
=head3 BeforeDecrypt
Called before the message is decoded or decrypted. Its return value is
ignored; it is passed the following parameters:
=over
=item Message
A L<MIME::Entity> object representing the mail. This may be modified by
the plugin.
=item RawMessage
A reference to the string containing the original message. This should
not be modified.
=item Queue
A L<RT::Queue>, the C<--queue> argument which was passed L<rt-mailgate>.
=item Actions
An array reference of actions to perform; the C<--action> argument which
was passed to L<rt-mailgate>. This may be modified.
=back
=head3 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:
=over
=item Message
A L<MIME::Entity> object representing the mail. This may be modified by
the plugin.
=item RawMessage
A reference to the string containing the original message. This should
not be modified.
=item Queue
A L<RT::Queue>, the C<--queue> argument which was passed L<rt-mailgate>.
=item Actions
An array reference of actions to perform; the C<--action> argument which
was passed to L<rt-mailgate>. This may be modified.
=back
=head3 GetCurrentUser
This method is called in order on the mail plugins that define it. The
first method to return a L<RT::CurrentUser> value shortcuts all other
plugins. It is passed:
=over
=item Message
A L<MIME::Entity> object representing the mail. This may be modified by
the plugin.
=item RawMessage
A reference to the string containing the original message. This should
not be modified.
=item Ticket
A L<RT::Ticket>, the ticket (if any) that has been extracted from the
subject. If there was no ticket id, this value will be a L<RT::Ticket>
object with no C<id>.
=item Queue
A L<RT::Queue>, the C<--queue> argument which was passed L<rt-mailgate>.
=back
=head3 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 I<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 C<take-correspond>, where the
C<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:
=over
=item Message
A L<MIME::Entity> object representing the mail. This may be modified by
the plugin.
=item CurrentUser
A L<RT::CurrentUser> object representing the authenticated user.
=item Action
A string representing the action to be undertaken.
=item Ticket
A L<RT::Ticket>, the ticket (if any) that has been extracted from the
subject. If there was no ticket id, this value will be a L<RT::Ticket>
object with no C<id>.
=item Queue
A L<RT::Queue>, the C<--queue> argument which was passed L<rt-mailgate>.
=back
=head3 HandleI<Action>
For any given action I<foo>, the presence of a subroutine called
C<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:
=over
=item Message
A L<MIME::Entity> object representing the mail. This may be modified by
the plugin.
=item Subject
A string, the original C<Subject> header of the message before it was
modified to extract the ticket id.
=item CurrentUser
A L<RT::CurrentUser> object representing the authenticated user.
=item Ticket
A L<RT::Ticket>, the ticket (if any) that has been extracted from the
subject. If there was no ticket id, this value will be a L<RT::Ticket>
object with no C<id>.
=item 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 C<Ticket> argument.
=item Queue
A L<RT::Queue>, the C<--queue> argument which was passed L<rt-mailgate>.
=back
=head1 SEE ALSO
L<RT::Interface::Email::Role>
=cut
|
