- 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 and searches for [subjecttag #id]

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