RT 5.0.3 Documentation
RT::Interface::Email
- NAME
- METHODS
- RECEIVING MAIL
- Gateway ARGSREF
- Plugins Method => name, Code => 0
- GetCurrentUser Message => message, Ticket => ticket, Queue => queue
- CheckACL Action => action, CurrentUser => user, Ticket => ticket, Queue => queue
- HandleAction Action => action, Message => message, Ticket => ticket, Queue => queue
- ParseSenderAddressFromHead HEAD
- ParseErrorsToAddressFromHead HEAD
- IsMachineGeneratedMail Message => message
- CheckForLoops HEAD
- CheckForAutoGenerated HEAD
- ExtractTicketId
- ParseTicketId
- MailError PARAM HASH
- SENDING EMAIL
- SendEmail Entity => undef, [ Bounce => 0, Ticket => undef, Transaction => undef ]
- Signing and Encrypting
- PrepareEmailUsingTemplate Template => '', Arguments => {}
- SendEmailUsingTemplate Template => '', Arguments => {}, From => CorrespondAddress, To => '', Cc => '', Bcc => ''
- GetForwardFrom Ticket => undef, Transaction => undef
- GetForwardAttachments Ticket => undef, Transaction => undef
- SignEncrypt Entity => undef, Sign => 0, Encrypt => 0
- DeleteRecipientsFromHead HEAD RECIPIENTS
- EncodeToMIME
- ConvertBlockquoteIndentsToQuotemarks
- ConvertHTMLToText HTML
- RECEIVING MAIL
NAME
RT::Interface::Email - helper functions for parsing and sending email
METHODS
RECEIVING MAIL
Gateway ARGSREF
Takes parameters:
action
-
A
-
separated list of actions to run. Standard actions, as detailed in "rt-mailgate" in bin, arecomment
andcorrespond
. The RT::Interface::Email::Action::Take and RT::Interface::Email::Action::Resolve plugins can be added to "@MailPlugins" in RT_Config to providetake
andresolve
actions, respectively. queue
-
The queue that tickets should be created in, if no ticket id is found on the message. Can be either a name or an id; defaults to 1.
message
-
The content of the message, as obtained from the MTA.
ticket
-
Optional; this ticket id overrides any ticket number derived from the subject.
Secrypts and verifies the message, decodes the transfer encoding, determines the user that the mail was sent from, and performs the given actions.
Returns a list of (status, message, ticket)
. The status
is -75 for a temporary failure (to be retried later bt the MTA), 0 for a permanent failure which did not result in a ticket, and 1 for a ticket that was found and acted on.
Plugins Method => name
, Code => 0
Returns the list of subroutine references for the given method name
from the configured "@MailPlugins" in RT_Config. If Code
is passed a true value, includes anonymous subroutines found in @MailPlugins
.
GetCurrentUser Message => message
, Ticket => ticket
, Queue => queue
Dispatches to the @MailPlugins
to find one the provides GetCurrentUser
that recognizes the current user. Mail plugins are tried one at a time, and stops after the first to return a current user. Anonymous subroutine references found in @MailPlugins
are treated as GetCurrentUser
methods.
The default GetCurrentUser authenticator simply looks at the From: address, and loads or creates a user accordingly; see RT::Interface::Email::Auth::MailFrom.
Returns the current user; on failure of any plugin to do so, stops processing with a permanent failure and sends a generic "Permission Denied" mail to the user.
CheckACL Action => action
, CurrentUser => user
, Ticket => ticket
, Queue => queue
Checks that the currentuser can perform a particular action. While RT's standard permission controls apply, this allows a better error message, or more limited restrictions on the email gateway.
Each plugin in @MailPlugins
which provides CheckACL
is given a chance to allow the action. If any returns a true value, it short-circuits all later plugins. Note that plugins may short-circuit and abort with failure of their own accord.
Aborts processing, sending a "Permission Denied" mail to the user with the last plugin's failure message, on failure.
HandleAction Action => action
, Message => message
, Ticket => ticket
, Queue => queue
Dispatches to the first plugin in @MailPlugins
which provides a HandleFoo
where Foo
is ucfirst(action)
.
ParseSenderAddressFromHead HEAD
Takes a MIME::Header object. Returns a list of (email address, friendly name, errors) where the address and name are the first address found in Reply-To
, From
, or Sender
.
A list of error messages may be returned even when an address is found, since it could be a parse error for another (checked earlier) sender field. In this case, the errors aren't fatal, but may be useful to investigate the parse failure.
ParseErrorsToAddressFromHead HEAD
Takes a MIME::Header object. Returns the first email address found in Return-path
, Errors-To
, Reply-To
, From
, or Sender
.
IsMachineGeneratedMail Message => message
Checks if the mail is machine-generated (via a bounce, mail headers,
CheckForLoops HEAD
Takes a MIME::Head object and returns true if the message was sent by this RT instance, by checking the X-RT-Loop-Prevention
header.
CheckForAutoGenerated HEAD
Takes a HEAD object of MIME::Head class and returns true if message is autogenerated. Checks Precedence
, RFC3834 Auto-Submitted
, and X-FC-Machinegenerated
fields of the head in tests.
ExtractTicketId
Passed a MIME::Entity object, and returns a either ticket id or undef to signal 'new ticket'.
This is a great entry point if you need to customize how ticket ids are handled for your site. RT::Extension::RepliesToResolved demonstrates one possible use for this extension.
If the Subject of the MIME::Entity is modified, the updated subject will be used during ticket creation.
ParseTicketId
Takes a string (the email subject) and searches for [subjecttag #id]
For customizations, the MIME::Entity object is passed as the second argument.
Returns the id if a match is found. Otherwise returns undef.
MailError PARAM HASH
Sends an error message. Takes a param hash:
- From
-
Sender's address, defaults to "$CorrespondAddress" in RT_Config;
- To
-
Recipient, defaults to "$OwnerEmail" in RT_Config;
- Subject
-
Subject of the message, defaults to
There has been an error
; - Explanation
-
Main content of the error, default value is
Unexplained error
; - MIMEObj
-
Optional MIME::Entity that is attached to the error mail. Additionally, the
In-Reply-To
header will point to this message. - Attach
-
Optional text that attached to the error as a
message/rfc822
part. - LogLevel
-
Log level the subject and explanation is written to the log; defaults to
critical
.
SENDING EMAIL
SendEmail Entity => undef, [ Bounce => 0, Ticket => undef, Transaction => undef ]
Sends an email (passed as a MIME::Entity object ENTITY
) using RT's outgoing mail configuration. If BOUNCE
is passed, and is a true value, the message will be marked as an autogenerated error, if possible. Sets Date field of the head to now if it's not set.
If the X-RT-Squelch
header is set to any true value, the mail will not be sent. One use is to let extensions easily cancel outgoing mail.
Ticket and Transaction arguments are optional. If Transaction is specified and Ticket is not then ticket of the transaction is used, but only if the transaction belongs to a ticket.
Returns 1 on success, 0 on error or -1 if message has no recipients and hasn't been sent.
Signing and Encrypting
This function as well signs and/or encrypts the message according to headers of a transaction's attachment or properties of a ticket's queue. To get full access to the configuration Ticket and/or Transaction arguments must be provided, but you can force behaviour using Sign and/or Encrypt arguments.
The following precedence of arguments are used to figure out if the message should be encrypted and/or signed:
* if Sign or Encrypt argument is defined then its value is used
* else if Transaction's first attachment has X-RT-Sign or X-RT-Encrypt header field then it's value is used
* else properties of a queue of the Ticket are used.
PrepareEmailUsingTemplate Template => '', Arguments => {}
Loads a template. Parses it using arguments if it's not empty. Returns a tuple (RT::Template object, error message).
Note that even if a template object is returned MIMEObj method may return undef for empty templates.
SendEmailUsingTemplate Template => '', Arguments => {}, From => CorrespondAddress, To => '', Cc => '', Bcc => ''
Sends email using a template, takes name of template, arguments for it and recipients.
GetForwardFrom Ticket => undef, Transaction => undef
Resolve the From field to use in forward mail
GetForwardAttachments Ticket => undef, Transaction => undef
Resolve the Attachments to forward
SignEncrypt Entity => undef, Sign => 0, Encrypt => 0
Signs and encrypts message using RT::Crypt, but as well handle errors with users' keys.
If a recipient has no key or has other problems with it, then the unction sends a error to him using 'Error: public key' template. Also, notifies RT's owner using template 'Error to RT owner: public key' to inform that there are problems with users' keys. Then we filter all bad recipients and retry.
Returns 1 on success, 0 on error and -1 if all recipients are bad and had been filtered out.
DeleteRecipientsFromHead HEAD RECIPIENTS
Gets a head object and list of addresses. Deletes addresses from To, Cc or Bcc fields.
EncodeToMIME
Takes a hash with a String and a Charset. Returns the string encoded according to RFC2047, using B (base64 based) encoding.
String must be a perl string, octets are returned.
If Charset is not provided then $EmailOutputEncoding config option is used, or "latin-1" if that is not set.
ConvertBlockquoteIndentsToQuotemarks
Given plain text that has been converted from HTML to text, adjust it to quote blockquote regions with ">".
ConvertHTMLToText HTML
Takes HTML characters and converts it to plain text characters. Appropriate for generating a plain text part from an HTML part of an email. Returns undef if conversion fails.
← Back to index