522 lines
15 KiB
HTML
522 lines
15 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::Mail - A simple interface to parsing, sending, and creating email.</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#creating_a_new_gt__mail_object">Creating a new GT::Mail object</a></li>
|
|
<li><a href="#parser__set_or_get_the_parse_object_">parser - Set or get the parse object.</a></li>
|
|
<li><a href="#parse__parsing_an_email_">parse - Parsing an email.</a></li>
|
|
<li><a href="#parse_head__parsing_just_the_head_">parse_head - Parsing just the head.</a></li>
|
|
<li><a href="#send__sending_an_email_">send - Sending an email.</a></li>
|
|
<li><a href="#top_part__getting_a_parts_object_">top_part - Getting a Parts object.</a></li>
|
|
<li><a href="#new_part__creating_a_parts_object_">new_part - Creating a Parts object.</a></li>
|
|
<li><a href="#attach__attaching_to_an_email_">attach - Attaching to an email.</a></li>
|
|
<li><a href="#to_string__getting_the_email_as_a_string_">to_string - Getting the email as a string.</a></li>
|
|
<li><a href="#as_string__getting_the_email_as_a_string_">as_string - Getting the email as a string.</a></li>
|
|
<li><a href="#build_email__building_an_email_">build_email - Building an email.</a></li>
|
|
<li><a href="#write__writing_an_email_to_a_file_handle_">write - Writing an email to a file handle.</a></li>
|
|
<li><a href="#naming__setting_the_naming_scheme_">naming - Setting the naming scheme.</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::Mail - A simple interface to parsing, sending, and creating email.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
use GT::Mail;
|
|
|
|
# Create and Sending
|
|
GT::Mail->send(
|
|
smtp => 'gossamer-threads.com',
|
|
smtp_port => 110, # optional; 110/465 (normal/SSL) will be used for the default
|
|
smtp_ssl => 1, # establish an SSL connection. Requires Net::SSLeay 1.06 or newer.
|
|
to => 'scott@gossamer-threads.com',
|
|
from => 'scott@gossamer-threads.com',
|
|
subject => 'Hello!!',
|
|
msg => 'I am a text email'
|
|
) or die "Error: $GT::Mail::error";
|
|
|
|
# Parsing and sending
|
|
my $mail = GT::Mail->new(debug => 1);</pre>
|
|
<pre>
|
|
# Parse an email that is in a file called mail.test
|
|
my $parser = $mail->parse('mail.test') or die "Error: $GT::Mail::error";
|
|
|
|
# Change who it is to
|
|
$parser->set("to", 'scott@gossamer-threads.com');</pre>
|
|
<pre>
|
|
# Add an attachment to it
|
|
$mail->attach (
|
|
type => 'text/plain',
|
|
encoding => '-guess',
|
|
body_path => 'Mail.pm',
|
|
filename => 'Mail.pm'
|
|
);
|
|
|
|
# Send the email we just parsed and modified
|
|
$mail->send(sendmail => '/usr/sbin/sendmail') or die "Error: $GT::Mail::error";</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::Mail is a simple interface for parsing, creating, and sending email. It
|
|
uses GT::Mail::Send to send email and GT::Mail::Parse to parse and store email
|
|
data structurs. All the creation work is done from within GT::Mail.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="creating_a_new_gt__mail_object">Creating a new GT::Mail object</a></h2>
|
|
<p>The arguments to <code>new()</code> in GT::Mail are mostly the same for all the class
|
|
methods in GT::Mail so I will be refering back to these further down. Mostly
|
|
these arguments are used to set parts of the header for creating an email. The
|
|
arguments can be passed in as either a hash or a hash ref. Any arguments aside
|
|
from these will be added to the content header as raw header fields. The
|
|
following is a list of the keys and a brief description.</p>
|
|
<dl>
|
|
<dt><strong><a name="item_debug">debug</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the debug level for this object. Anything but zero will produce ouput on
|
|
STDERR.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_disposition">disposition</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the Content-Disposition.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_filename">filename</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the Content-Disposition to attachment and the file name to what to
|
|
specify.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_encoding">encoding</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the Content-Transfer-Encoding (You really should not set this).
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_type">type</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the Content-Type.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_body_data">body_data</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the top level body data to the in memory string specified.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_msg">msg</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Same as body_data.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_body_handle">body_handle</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the top level body to the File Handle.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_body_path">body_path</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the top level body path.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parser__set_or_get_the_parse_object_">parser - Set or get the parse object.</a></h2>
|
|
<pre>
|
|
my $parser = $mail->parser;
|
|
$mail->parser($parser);</pre>
|
|
<p>Set or get method for the parser object that is used when you call <code>parse_head()</code>
|
|
or parse(). This object must conform to the method parse and parse_head. If no
|
|
object is passed to this method a <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parse.html">the GT::Mail::Parse manpage</a> object is created when
|
|
needed.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse__parsing_an_email_">parse - Parsing an email.</a></h2>
|
|
<p>Instance method that returns a parts object. Emails are stored recursivly in
|
|
parts object. That is emails can have parts within parts within parts etc.. See
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parts.html">the GT::Mail::Parts manpage</a> for details on the methods supported by the parts object
|
|
that is returned.</p>
|
|
<p>The <code>parse()</code> method takes only one argument. It can be a GLOB ref to a file
|
|
handle, a FileHandle object, or the path to a file. In any case the IO must
|
|
contain a valid formated email.</p>
|
|
<p>Once an email is parsed, you can make changes to it as you need and call the
|
|
send method to send it or call the write method to write it to file, etc.</p>
|
|
<p>This method will return false if an error occurs when parsing. The error
|
|
message will be set in $GT::Mail::error.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse_head__parsing_just_the_head_">parse_head - Parsing just the head.</a></h2>
|
|
<p>This method does the exact same thing as the parse method but it will only
|
|
parse the top level header of the email. Any IO's will be reset after the
|
|
parsing.</p>
|
|
<p>Use this method if whether you want to parse and decode the body of the email
|
|
depends on what is in the header of the email or if you only need access to the
|
|
header. None of the parts will contain a body.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="send__sending_an_email_">send - Sending an email.</a></h2>
|
|
<p>Class/Instance method for sending email. It sends the currently in memory
|
|
email. This means, if you parse an email, that email is in memory, if you
|
|
specify params for an email to new(), that is the email that gets sent. You can
|
|
also specify the params for the email to this method.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="top_part__getting_a_parts_object_">top_part - Getting a Parts object.</a></h2>
|
|
<p>Instance method to set or get the top level part. If you are setting this, the
|
|
object must be from <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parts.html">the GT::Mail::Parts manpage</a>. You can use this to retrieve the part
|
|
object after you specify params to create an email. This object will contain
|
|
all the other parts for the email. e.g. attachments and emails that are
|
|
attached. See <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parts.html">the GT::Mail::Parts manpage</a> for more details on this object.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="new_part__creating_a_parts_object_">new_part - Creating a Parts object.</a></h2>
|
|
<p>Instance method to get a new part object. This method takes the same arguments
|
|
as the <code>new()</code> constructor. Returns the new part object. The part object is
|
|
added to the current email only if arguments are given otherwize just returns
|
|
an empty part.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="attach__attaching_to_an_email_">attach - Attaching to an email.</a></h2>
|
|
<p>Instance method to attach to the in memory email. You can pass in a GT::Mail
|
|
object or you can pass the same arguments you would pass to <code>new()</code> to specify
|
|
all the information about the attachment. In addition if you specify a file
|
|
path and do not specify a mime type, this will attempt to guess the mime type
|
|
from the file extention.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="to_string__getting_the_email_as_a_string_">to_string - Getting the email as a string.</a></h2>
|
|
<p>Returns the entire email as a string. Do not use this function if you have
|
|
attachments and are worried about memory ussage.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="as_string__getting_the_email_as_a_string_">as_string - Getting the email as a string.</a></h2>
|
|
<p>Same as to_string.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="build_email__building_an_email_">build_email - Building an email.</a></h2>
|
|
<p>Instance method that builds the currently in memory email. This method takes
|
|
one argument, a code ref. It calles the code ref with one argument. The code
|
|
ref is called for each section of the email that is created. A good example of
|
|
how to use this is what the as_string method does:</p>
|
|
<pre>
|
|
my $ret = '';
|
|
$obj->build_email(sub { $ret .= $_[0] });</pre>
|
|
<p>This puts the entire created email into the string $ret. You can use this, for
|
|
example to print the email to a filehandle (which is what the <code>write()</code> method
|
|
does).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="write__writing_an_email_to_a_file_handle_">write - Writing an email to a file handle.</a></h2>
|
|
<p>Instance mothod that writes the currently in memory email to a file or file
|
|
handle. The only arguments this method takes is a file or a reference to a glob
|
|
that is a filehandle or FileHandle object.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="naming__setting_the_naming_scheme_">naming - Setting the naming scheme.</a></h2>
|
|
<p>Instance method to specify a naming scheme for parsing emails. Calling this
|
|
after the email is parsed has no effect. This method just wraps to the one in
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/Mail/Parse.html">the GT::Mail::Parse manpage</a>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>Revision: $Id: Mail.pm,v 1.70 2004/11/04 20:23:09 brewt Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|