NAME

Petal::Mail - Format text e-mail using Petal

SYNOPSIS

  use Petal::Mail;
  use Petal::Mail;
  use Petal::Mail;
  use Petal::Mail;
  my $petal_mail = new Petal::Mail ('email.xml');
  my $text_mail  = $petal_mail->process (%args);

SUMMARY

Petal::Mail processes a Petal XML template, and then turns the resulting XML into a text email which can be sent through sendmail or other. The XML has to follow a certain syntax which is defined in this documentation.

Since Petal::Mail's is a subclass of Petal, its API is the same. Which means you need to read about Petal before you can use Petal::Mail.

GLOBAL / LOCAL VARIABLES

local $Petal::Mail::Line_Wrap = 68;

Amounts of characters allowed before text-flowed wrapping.

local $Petal::Mail::Indent = 4;

Amounts of whitespace when indenting <dd> tags

local $Petal::Mail::Sendmail = '/usr/sbin/sendmail -t';

If you set this variable to your sendmail executable, and make sure the $ENV{SERVER_ADMIN} is set to a proper email address for processing bounces, then you can use the send() method instead of the process() method and Petal::Mail will send the email once it's been created.

FUNCTIONS

process

This function processes a template. It takes a hash or hashref which is used to fill out any elements in the template. It returns the processed template as a string. See Petal for further details.

FUNCTIONS

process

This function processes a template. It takes a hash or hashref which is used to fill out any elements in the template. It returns the processed template as a string. See Petal for further details. =head2 send

This function processes a template and sends an email message according to the headers in the template. It takes the same parameters as process in addition to the email address of the authorized sender. The authorized sender may also be set with the environment parameter 'SERVER_ADMIN'. Returns null on success or dies on failure.

        $petal_mail->send(AUTH_SENDER => 'lewis@carroll.net', %args);

FUNCTIONS

process

This function processes and sends an email message according to a template. It takes the same parameters as process. Returns null(?) on success or dies on failure.

FUNCTIONS

process

This function processes and sends an email message according to a template. It takes the same parameters as process. Returns null(?) on success or dies on failure.

send

This function processes and sends an email message according to a template. It takes the same parameters as process. Returns null(?) on success or dies on failure.

XML Syntax

For Petal::Mail to work properly, your resulting XML template must implement the following syntax:

  <Message>
    <Header1>Value1</Header1>
    <Header2>Value2</Header2>
    <Header3>Value3</Header3>
    <body>
      <p>First Paragraph</p>
      <pre>Preformatted Text</pre>
      <dl>
        <dt>Definition Term</dt>
=back

Text contained in tags will ignore white space characters (e.g., extra spaces, tabs, carriage returns, etc.). See the XHTML specs at W3C for complete details-- http://www.w3.org/MarkUp/. <dd>Definition List</dd> </dl> </Body> </Message>

As you can see, Petal::Mail's template syntax is quite simple:

It has one top element <Message> tag
Each header is defined in a <Header> tag which MUST be a direct child of <Message>
The body of the message is defined in the <Body> tag

Text contained in tags will ignore white space characters (e.g., extra spaces, tabs, carriage returns, etc.). See the XHTML specs at W3C for complete details-- http://www.w3.org/MarkUp/. =back

As you can see, the content of the <Body> seems to be XHTML. However only a subset of XHTML is supported and some extra limitations:

Text contained in tags will ignore white space characters (e.g., extra spaces, tabs, carriage returns, etc.). See the XHTML specs at W3C for complete details-- http://www.w3.org/MarkUp/.

* Paragraphs ""

* Preformatted text "<pre>"

* Definition lists "<dl>, <dt>, <dd>"

* Anything which is outside , <pre>, <dt>, <dd> tags will be ignored / stripped out

Text contained in tags will ignore white space characters (e.g., extra spaces, tabs, carriage returns, etc.). See the XHTML specs at W3C for complete details-- http://www.w3.org/MarkUp/.

Silly Example

Here's an example of an acceptable XML SPAM^H^H^H^H Email syntax. For simplicity here I haven't used any TAL attributes, but you could have as much TAL stuff as you'd want in there.

(I hope Damian doesn't mind my bad sense of humor)

  <Message>
    <Content-Type>text/plain; charset=utf-8; format=flowed</Content-Type>
    <Content-Disposition>inline</Content-Disposition>
    <Content-Transfer-Encoding>8bit</Content-Transfer-Encoding>
    <Content-Language>en</Content-Language>
    <MIME-Version>1.0</MIME-Version>
    <From>Mark Conway &lt;mark@bruce.csse.monash.edu.au&gt;</From>
    <To>Yourself &lt;your@self.net&gt;</To>
    <Subject>Please help me with important transaction</Subject>
    <User-Agent>MKDoc::Mail 0.1</User-Agent>
    <Precedence>bulk</Precedence>
    <Organization>Rather Messy</Organization>

    <body xmlns="http://www.w3.org/1999/xhtml">
      <p>Dear yourself,</p>

      <p>My name is Mark Conway. I am one of Damian Conway's illegitimate sons,
      the very famous Perl hacker who bringed tons of great crazy Perl modules.
      </p>

      <p>Unfortunately Damian, as you are aware, has been trampled by a Camel
      on his holiday to egypt. However, I had the surprise of being sent a letter of
      last will from Damian, who did not forgetting his secret sons.</p>

      <p>Damian left me the incredible amounts of FIFTY MILLION LINES OF OBFUSCATED
      PERL CODE (OPC 50,000,000.00) so that I can be seen as a great hacker and get
      some acknowledgement too.</p>

      <p>However I currently cannot publish this code because of USA and
      European patent laws. Since you live in Nigeria, I would request your
      cooperation for a mutually exceptionally profitable business.</p>

      <p>The operation would proceed as follows:</p>

      <dl>
        <dt>CPAN Account</dt>
        <dd>You give me your CPAN account username and password</dd>

        <dt>Login</dt>
        <dd>I log in CPAN as you</dd>

        <dt>Upload</dt>

        <dd>I delete all your code from... euh... I upload the FIFTY MILLION
        LINES OF OBFUSCATED PERL CODE (OPC 50,000,000.00) in your CPAN account</dd>

        <dt>Which gives you...</dt>
        <dd>Fame!</dd>
      </dl>

      <p>Of course, as a compensation, I will subscribe myself as a module
      co-author, effectively grabbing about half the fame you'll get for these
      modules. Which will still leave you a whopping TWENTY FIVE MILLION LINES OF
      OBFUSCATED PERL CODE (OPC 25,000,000.00)</p>

     <pre>-- 
  Yours Faithfully,
  Mark Conway, Illegitimate Son</pre>
    </body>
  </Message>

This gives the following output:

  Content-Type: text/plain; charset=utf-8; format=flowed
  Content-Disposition: inline
  Content-Transfer-Encoding: 8bit
  Content-Language: en
  MIME-Version: 1.0
  From: Mark Conway <mark@bruce.csse.monash.edu.au>
  Message-ID: <1067607400.IJCVT@bruce.csse.monash.edu.au>
  To: Yourself <your@self.net>
  Subject: Please help me with important transaction
  User-Agent: MKDoc::Mail 0.1
  Precedence: bulk
  Organization: Rather Messy

  Dear yourself,

  My name is Mark Conway. I am one of Damian Conway's illegitimate 
  sons, the very famous Perl hacker who bringed tons of great crazy 
  Perl modules.

  Unfortunately Damian, as you are aware, has been trampled by a Camel 
  on a holiday to egypt. However, I had the surprise of being sent a 
  letter from Damian. Not forgetting his secret son.

  Damian left me the incredible amounts of FIFTY MILLION LINES OF 
  OBFUSCATED PERL CODE (OPC 50,000,000.00) so that I can be seen as a 
  great hacker and get some acknowledgement too.

  However I currently cannot publish this code because of USA and 
  European patent law. Since you live in Nigeria, I would request your 
  cooperation for a mutually profitable business.

  The operation would proceed as follows:

  CPAN Account
      You give me your CPAN account username and password

  Login
      I log in CPAN as you

  Upload
      I remove all the code from... euh... I upload the FIFTY MILLION 
      LINES OF OBFUSCATED PERL CODE (OPC 50,000,000.00) in your CPAN 
      account

  Which gives...
      Fame!

  Of course, as a compensation, I will subscribe myself as a module 
  co-author, effectively grabbing about half the fame you'll get for 
  these modules. Which will still leave you a whopping TWENTY FIVE 
  MILLION LINES OF OBFUSCATED PERL CODE (OPC 25,000,000.00)

  -- 
  Yours Faithfully,
  Mark Damian, Illegitimate Son

Note that the Message-ID is automatically generated from the <From> contents. If you're not careful, SpamAssasin will pickup on inconsistant Message-ID, which would make your SPAM^H^H^H^H informative newsletters useless.

Also note that the message headers are automatically MIME encoded using the Encode module's 'MIME-Header' encoding facility.

BUGS

Probably plenty.

AUTHOR

Author: Jean-Michel Hiver

This module is free software and is distributed under the same license as Perl itself. Use it at your own risk.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 91:: =cut found outside a pod block. Skipping to next block.
Around line 428:: =over should be: '=over' or '=over positive_number'
You can't have =items (as at line 435) unless the first thing after the =over is an =item