view release on metacpan or  search on metacpan

lib/Email/Send.pm  view on Meta::CPAN

=head1 DESCRIPTION

This module provides a very simple, very clean, very specific interface
to multiple Email mailers. The goal of this software is to be small
and simple, easy to use, and easy to extend.

=head2 Constructors

=over 4

=item new

  my $sender = Email::Send->new({
      mailer      => 'NNTP',
      mailer_args => [ Host => 'nntp.example.com' ],
  });

Create a new mailer object. This method can take parameters for any of the data
properties of this module. Those data properties, which have their own accessors,
are listed under L<"Properties">.

=back

=head2 Properties

=over 4

=item mailer

The mailing system you'd like to use for sending messages with this object.
This is not defined by default. If you don't specify a mailer, all available
plugins will be tried when the C<send> method is called until one succeeds.

=item mailer_args

Arguments passed into the mailing system you're using.

=item message_modifier

If defined, this callback is invoked every time the C<send> method is called
on an object. The mailer object will be passed as the first argument. Second,
the actual C<Email::Simple> object for a message will be passed. Finally, any
additional arguments passed to C<send> will be passed to this method in the
order they were received.

This is useful if you are sending in bulk.

=back

=cut

sub new {
    my ($class, $args) = @_;
    $args->{mailer_args} ||= [];
    my %plugins = map {
        my ($short_name) = /^Email::Send::(.+)/;
        ($short_name, $_);
    } $class->plugins;
    $args->{_plugin_list} = \%plugins;
    return bless $args => $class;
}

BEGIN {
  for my $field (qw(mailer mailer_args message_modifier _plugin_list)) {
    my $code = sub {
      return $_[0]->{$field} unless @_ > 1;
      my $self = shift;
      $self->{$field} = (@_ == 1 ? $_[0] : [@_]);
    };

    no strict 'refs';
    *$field = $code;
  }
}

=head2 METHODS

=over 4

=item send

  my $result = $sender->send($message, @modifier_args);

Send a message using the predetermined mailer and mailer arguments. If you
have defined a C<message_modifier> it will be called prior to sending.

The first argument you pass to send is an email message. It must be in some
format that C<Email::Abstract> can understand. If you don't have
C<Email::Abstract> installed then sending as plain text or an C<Email::Simple>
object will do.

Any remaining arguments will be passed directly into your defined
C<message_modifier>.

=cut

sub send {
    goto &_send_function unless eval { $_[0]->isa('Email::Send') };
    my ($self, $message, @args) = @_;

    my $simple = $self->_objectify_message($message);
    return failure "No message found." unless $simple;

    $self->message_modifier->(
        $self, $simple,
        @args,
    ) if $self->message_modifier;

    if ( $self->mailer ) {
        return $self->_send_it($self->mailer, $simple);
    }

    return $self->_try_all($simple);
}

=item all_mailers

  my @available = $sender->all_mailers;

Returns a list of available mailers. These are mailers that are