/ 
Petal-Mail-0.1
River stage one • 1 direct dependent • 1 total dependent
/ Petal::Mail

NAME

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

SYNOPSIS

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.

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>
      <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

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:

  • Paragraphs "<p>"

  • Preformatted text "<pre>"

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

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

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

Copyright 2003 - MKDoc Holdings Ltd.

Author: Jean-Michel Hiver <jhiver@mkdoc.com>

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

SEE ALSO

Petal: http://search.cpan.org/author/JHIVER/Petal/
MKDoc: http://www.mkdoc.com/

Help us open-source MKDoc. Join the mkdoc-modules mailing list:

mkdoc-modules@lists.webarch.co.uk

1 POD Error

The following errors were encountered while parsing the POD:

Around line 354:

You forgot a '=back' before '=head1'