GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PETAL::MAIL (3)

.ds Aq ’

NAME

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

CONTENTS

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 CW$Petal::Mail::Line_Wrap = 68;

Amounts of characters allowed before text-flowed wrapping.

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

Amounts of whitespace when indenting <dd> tags

local CW$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 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 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 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 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 <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:
o It has one top element <Message> tag
o Each header is defined in a <Header> tag which MUST be a direct child of <Message>
o 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

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

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

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/dist/Petal/
  MKDoc: http://www.mkdoc.com/



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



  mkdoc-modules@lists.webarch.co.uk



POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
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

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PETAL::MAIL (3) 2005-03-16

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.