Bric::Util::Trans::Mail(3p)

NAME
Bric::Util::Trans::Mail - Utility class for sending email.

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2006-03-18 01:26:34 +0100 (Sat, 18 Mar 2006) $

SYNOPSIS
  use Bric::Util::Trans::Mail;
  my $m = Bric::Util::Trans::Mail->new(
    { smtp    => 'mail.sourceforge.net',
      from    => 'bricolage-devel@lists.sourceforge.net',
      to      => ['joe@example.com'],
      subject => 'Greetings',
      message => 'This is a message sent via Bric::Util::Trans::Mail'
     });
  $m->send;

DESCRIPTION
This class provides a thin abstraction to the MIME::Entity and Net::SMTP modules. Use it to send email from within Bricolage applications. Or from within other applications. We don't care.

INTERFACE

  Constructors

my $mail = Bric::Util::Trans::Mail->new($init)
    Instantiates a Bric::Util::Trans::Mail object. An anonymous of initial values may be passed. The supported intial value keys are:

    *   smtp - String with the DNS name of the SMTP server. Defaults to value of the SMTP_SERVER constant in Bric::Config.

    *   from - String with sender's email address.

    *   to - Anonymous array of email addresses to send mail to.

    *   cc - Anonymous array of email address to Cc email to.

    *   bcc - Anonymous array of email addresses to Bcc email to.

    *   content_type - The content type of the email. Defaults to "text/plain" if unspecified.

    *   subject - The subject of the message.

    *   message - The message to be sent.

    *   resources - Anonymous array of Bric::Dist::Resource objects representing files to send as attachments.

    Throws:

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    Side Effects: NONE.

    Notes: NONE.

  Destructors

$org->DESTROY
    Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

  Public Class Methods
NONE.

  Public Instance Methods

my $smtp = $mail->get_smtp
    Returns the DNS name of the SMTP server to which to send email.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'smtp' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_smtp($smtp)
    Sets the DNS name of the SMTP server to which to send email.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'smtp' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

my $from = $mail->get_from
    Returns the email address the message is to be sent from.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'from' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_from($from)
    Sets the email address from which to send the email.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'from' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

my $to_aref = $mail->get_to
    Returns an anonymous array of email address to which to send the mail.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'to' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_to($to_aref)
    Sets the list of email addresses to which to send the mail. Pass in the list as an anonymous array.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'to' required.

    *   No AUTOLOAD method.

    Side Effects: Parses out the one or more email addresses in each item in the array reference to use as the recipients. The string in each item will be used literally in the "From" header of the outgoing email. To change the recipients, pass in a new array reference rather than edit the existing array reference.

    Notes: NONE.

my $cc_aref = $mail->get_cc
    Returns an anonymous array of address to which to Cc the mail.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'cc' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_cc($cc_aref)
    Sets the list of email addresses to which to Cc the mail. Pass in the list as an anonymous array.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'cc' required.

    *   No AUTOLOAD method.

    Side Effects: Parses out the one or more email addresses in each item in the array reference to use as the recipients. The string in each item will be used literally in the "Cc" header of the outgoing email. To change the recipients, pass in a new array reference rather than edit the existing array reference.

    Notes: NONE.

my $bcc_aref = $mail->get_bcc
    Returns an anonymous array of address to which to Bcc the mail.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'bcc' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_bcc($bcc_aref)
    Sets the list of email addresses to which to Bcc the mail. Pass in the list as an anonymous array.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'bcc' required.

    *   No AUTOLOAD method.

    Side Effects: Parses out the one or more email addresses in each item in the array reference to use as the recipients. To change the recipients, pass in a new array reference rather than edit the existing array reference.

    Notes: NONE.

my $sub = $mail->get_content_type
    Returns the content type of the mail. Defaults to "text/plain" if unspecified.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'content_type' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_content_type($sub)
    Sets content type of the email.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'content_type' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

my $sub = $mail->get_subject
    Returns the subject of the mail.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'subject' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_subject($sub)
    Sets subject of the email.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'subject' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

my $msg = $mail->get_message
    Returns the message (body) of the email.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'message' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_message($msg)
    Sets message (body) of the email.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'message' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

my $resources_aref = $mail->get_resources
    Returns an anonymous array of Bric::Dist::Resource objects representing files to send as attachments. Returns "undef" if no resources are to be attached.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'resources' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->set_resources($resources_aref)
    Sets the anonymous array of Bric::Dist::Resource objects representing files to send as attachments.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'resources' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: NONE.

$self = $mail->send
$self = $mail->send($debug)
    Sends the email to the addresses stored in to, cc, and bcc. Pass in a true value in order to get debugging statements from Net::SMTP. This is useful to see excactly what's happening when you send email.

    Throws:

    *   Unable to send mail.

    Side Effects: NONE.

    Notes: NONE.

PRIVATE

  Private Class Methods
NONE.

  Private Instance Methods
NONE.

  Private Functions
NONE.

NOTES
NONE.

AUTHOR
David Wheeler <david@justatheory.com>

SEE ALSO
Bric, Bric::Dist::Resource, Bric::Dist::Action::Email, Net::SMTP, MIME::Entity