Petal::Mail - Format text e-mail using Petal
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);
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.
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.
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);
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.
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 <p> 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 <p> 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 <p> 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 "<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
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/dist/Petal/ MKDoc: http://www.mkdoc.com/
Help us open-source MKDoc. Join the mkdoc-modules mailing list:
mkdoc-modules@lists.webarch.co.uk
2 POD Errors
The following errors were encountered while parsing the POD:
=cut found outside a pod block. Skipping to next block.
=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
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.