• 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
    • ConvertHTMLToText HTML

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, are comment and correspond. The RT::Interface::Email::Action::Take and RT::Interface::Email::Action::Resolve plugins can be added to "@MailPlugins" in RT_Config to provide take and resolve 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.

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