NAME

GT::Mail - A simple interface to parsing, sending, and creating email.

SYNOPSIS

    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);
    # 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');
    # 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";

DESCRIPTION

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.

Creating a new GT::Mail object

The arguments to new() 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.

debug
Sets the debug level for this object. Anything but zero will produce ouput on STDERR.

disposition
Sets the Content-Disposition.

filename
Sets the Content-Disposition to attachment and the file name to what to specify.

encoding
Sets the Content-Transfer-Encoding (You really should not set this).

type
Sets the Content-Type.

body_data
Sets the top level body data to the in memory string specified.

msg
Same as body_data.

body_handle
Sets the top level body to the File Handle.

body_path
Sets the top level body path.

parser - Set or get the parse object.

    my $parser = $mail->parser;
    $mail->parser($parser);

Set or get method for the parser object that is used when you call parse_head() or parse(). This object must conform to the method parse and parse_head. If no object is passed to this method a the GT::Mail::Parse manpage object is created when needed.

parse - Parsing an email.

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 the GT::Mail::Parts manpage for details on the methods supported by the parts object that is returned.

The parse() 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.

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.

This method will return false if an error occurs when parsing. The error message will be set in $GT::Mail::error.

parse_head - Parsing just the head.

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.

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.

send - Sending an email.

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.

top_part - Getting a Parts object.

Instance method to set or get the top level part. If you are setting this, the object must be from the GT::Mail::Parts manpage. 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 the GT::Mail::Parts manpage for more details on this object.

new_part - Creating a Parts object.

Instance method to get a new part object. This method takes the same arguments as the new() 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.

attach - Attaching to an email.

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 new() 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.

to_string - Getting the email as a string.

Returns the entire email as a string. Do not use this function if you have attachments and are worried about memory ussage.

as_string - Getting the email as a string.

Same as to_string.

build_email - Building an email.

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:

    my $ret = '';
    $obj->build_email(sub { $ret .= $_[0] });

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 write() method does).

write - Writing an email to a file handle.

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.

naming - Setting the naming scheme.

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 the GT::Mail::Parse manpage.

COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

VERSION

Revision: $Id: Mail.pm,v 1.70 2004/11/04 20:23:09 brewt Exp $