Petal::Mail - Format text e-mail using Petal
my $petal_mail = new Petal::Mail ('email.xml'); my $text_mail = $petal_mail->process (%args);
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.
Amounts of characters allowed before text-flowed wrapping.
Amounts of whitespace when indenting <dd> tags
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.
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
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 <mark@bruce.csse.monash.edu.au></From> <To>Yourself <your@self.net></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.
Probably plenty.
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.
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:
You forgot a '=back' before '=head1'
To install Petal::Mail, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Petal::Mail
CPAN shell
perl -MCPAN -e shell install Petal::Mail
For more information on module installation, please visit the detailed CPAN module installation guide.