RT 4.2.17 Documentation

RT::Interface::Email

  RT::Interface::Email - helper functions for parsing email sent to RT

SYNOPSIS

  use lib "!!RT_LIB_PATH!!";
  use lib "!!RT_ETC_PATH!!";

  use RT::Interface::Email  qw(Gateway CreateUser);

DESCRIPTION

METHODS

CheckForLoops HEAD

Takes a HEAD object of MIME::Head class and returns true if the message's been sent by this RT instance. Uses "X-RT-Loop-Prevention" field of the head for test.

CheckForSuspiciousSender HEAD

Takes a HEAD object of MIME::Head class and returns true if sender is suspicious. Suspicious means mailer daemon.

CheckForAutoGenerated HEAD

Takes a HEAD object of MIME::Head class and returns true if message is autogenerated. Checks Precedence, Auto-Submitted, and X-FC-Machinegenerated fields of the head in tests.

MailError PARAM HASH

Sends an error message. Takes a param hash:

From - sender's address, by default is 'CorrespondAddress';
To - recipient, by default is 'OwnerEmail';
Bcc - optional Bcc recipients;
Subject - subject of the message, default is 'There has been an error';
Explanation - main content of the error, default value is 'Unexplained error';
MIMEObj - optional MIME entity that's attached to the error mail, as well we add 'In-Reply-To' field to the error that points to this message.
Attach - optional text that attached to the error as 'message/rfc822' part.
LogLevel - log level under which we should write the subject and explanation message into the log, by default we log it as critical.

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.

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.

ParseCcAddressesFromHead HASH

Takes a hash containing QueueObj, Head and CurrentUser objects. Returns a list of all email addresses in the To and Cc headers b<except> the current Queue's email addresses, the CurrentUser's email address and anything that the configuration sub RT::IsRTAddress matches.

ParseSenderAddressFromHead HEAD

Takes a MIME::Header object. Returns (user@host, friendly name, errors) where the first two values are the From (evaluated in order of Reply-To:, From:, Sender).

A list of error messages may be returned even when a Sender value 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. Return a single value : user@host of the From (evaluated in order of Return-path:,Errors-To:,Reply-To:, From:, Sender)

ParseAddressFromHeader ADDRESS

Takes an address from $head-get('Line')> and returns a tuple: user@host, friendly name

DeleteRecipientsFromHead HEAD RECIPIENTS

Gets a head object and list of addresses. Deletes addresses from To, Cc or Bcc fields.

ExtractTicketId

Passed a MIME::Entity. Returns a 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 this ticket is modified, it will be reloaded by the mail gateway code before Ticket creation.

ParseTicketId

Takes a string and searches for [subjecttag #id]

Returns the id if a match is found. Otherwise returns undef.

Gateway ARGSREF

Takes parameters:

    action
    queue
    message

This performs all the "guts" of the mail rt-mailgate program, and is designed to be called from the web interface with a message, user object, and so on.

Can also take an optional 'ticket' parameter; this ticket id overrides any ticket id found in the subject.

Returns:

    An array of:

    (status code, message, optional ticket object)

    status code is a numeric value.

      for temporary failures, the status code should be -75

      for permanent failures which are handled by RT, the status code
      should be 0

      for succces, the status code should be 1

GetAuthenticationLevel

    # Authentication Level
    # -1 - Get out.  this user has been explicitly declined
    # 0 - User may not do anything (Not used at the moment)
    # 1 - Normal user
    # 2 - User is allowed to specify status updates etc. a la enhanced-mailgate