Email::Send(3pm)

1Email::Send(3)        User Contributed Perl Documentation       Email::Send(3)
2
3
4

NAME

6       Email::Send - Simply Sending Email
7

SYNOPSIS

9         use Email::Send;
10
11         my $message = <<'__MESSAGE__';
12         To: recipient@example.com
13         From: sender@example.com
14         Subject: Hello there folks
15
16         How are you? Enjoy!
17         __MESSAGE__
18
19         my $sender = Email::Send->new({mailer => 'SMTP'});
20         $sender->mailer_args([Host => 'smtp.example.com']);
21         $sender->send($message);
22
23         # more complex
24         my $bulk = Email::Send->new;
25         for ( qw[SMTP Sendmail Qmail] ) {
26             $bulk->mailer($_) and last if $bulk->mailer_available($_);
27         }
28
29         $bulk->message_modifier(sub {
30             my ($sender, $message, $to) = @_;
31             $message->header_set(To => qq[$to\@geeknest.com])
32         });
33
34         my @to = qw[casey chastity evelina casey_jr marshall];
35         my $rv = $bulk->send($message, $_) for @to;
36

DESCRIPTION

38       This module provides a very simple, very clean, very specific interface
39       to multiple Email mailers. The goal of this software is to be small and
40       simple, easy to use, and easy to extend.
41
42       Constructors
43
44       new()
45             my $sender = Email::Send->new({
46                 mailer      => 'NNTP',
47                 mailer_args => [ Host => 'nntp.example.com' ],
48             });
49
50           Create a new mailer object. This method can take parameters for any
51           of the data properties of this module. Those data properties, which
52           have their own accessors, are listed under "Properties".
53
54       Properties
55
56       mailer
57           The mailing system you'd like to use for sending messages with this
58           object.  This is not defined by default. If you don't specify a
59           mailer, all available plugins will be tried when the "send()"
60           method is called until one succeeds.
61
62       mailer_args
63           Arguments passed into the mailing system you're using.
64
65       message_modifier
66           If defined, this callback is invoked every time the "send()" method
67           is called on an object. The mailer object will be passed as the
68           first argument. Second, the actual "Email::Simple" object for a
69           message will be passed. Finally, any additional arguments passed to
70           "send()" will be passed to this method in the order they were
71           recieved.
72
73           This is useful if you are sending in bulk.
74
75       Methods
76
77       send()
78             my $result = $sender->send($message, @modifier_args);
79
80           Send a message using the predetermined mailer and mailer arguments.
81           If you have defined a "message_modifier" it will be called prior to
82           sending.
83
84           The first argument you pass to send is an email message. It must be
85           in some format that "Email::Abstract" can understand. If you don't
86           have "Email::Abstract" installed then sending as plain text or an
87           "Email::Simple" object will do.
88
89           Any remaining arguments will be passed directly into your defined
90           "message_modifier".
91
92       all_mailers()
93             my @available = $sender->all_mailers;
94
95           Returns a list of availabe mailers. These are mailers that are
96           installed on your computer and register themselves as available.
97
98       mailer_available()
99             # is SMTP over SSL avaialble?
100             $sender->mailer('SMTP')
101               if $sender->mailer_available('SMTP', ssl => 1);
102
103           Given the name of a mailer, such as "SMTP", determine if it is
104           available. Any additional arguments passed to this method are
105           passed directly to the "is_available()" method of the mailer being
106           queried.
107
108       Writing Mailers
109
110         package Email::Send::Example;
111
112         sub is_available {
113             eval { use Net::Example }
114         }
115
116         sub send {
117             my ($class, $message, @args) = @_;
118             use Net::Example;
119             Net::Example->do_it($message) or return;
120         }
121
122         1;
123
124       Writing new mailers is very simple. If you want to use a short name
125       when calling "send", name your mailer under the "Email::Send" names‐
126       pace.  If you don't, the full name will have to be used. A mailer only
127       needs to implement a single function, "send". It will be called from
128       "Email::Send" exactly like this.
129
130         Your::Sending::Package->send($message, @args);
131
132       $message is an Email::Simple object, @args are the extra arguments
133       passed into "Email::Send::send".
134
135       Here's an example of a mailer that sends email to a URL.
136
137         package Email::Send::HTTP::Post;
138         use strict;
139
140         use vars qw[$AGENT $URL $FIELD];
141         use Return::Value;
142
143         sub is_available {
144             eval { use LWP::UserAgent }
145         }
146
147         sub send {
148             my ($class, $message, @args);
149
150             require LWP::UserAgent;
151
152             if ( @args ) {
153                 my ($URL, $FIELD) = @args;
154                 $AGENT = LWP::UserAgent->new;
155             }
156             return failure "Can't send to URL if no URL and field are named"
157                 unless $URL && $FIELD;
158             $AGENT->post($URL => { $FIELD => $message->as_string });
159             return success;
160         }
161
162         1;
163
164       This example will keep a UserAgent singleton unless new arguments are
165       passed to "send". It is used by calling "Email::Send::send".
166
167         my $sender = Email::Send->new({ mailer => 'HTTP::Post' });
168
169         $sender->mailer_args([ 'http://example.com/incoming', 'message' ]);
170
171         $sender->send($message);
172         $sender->send($message2); # uses saved $URL and $FIELD
173

AUTHOR

179       Current maintainer: Ricardo SIGNES, <rjbs@cpan.org>.
180
181       Original author: Casey West, <casey@geeknest.com>.
182

COPYRIGHT

184         Copyright (c) 2005 Casey West.  All rights reserved.
185         This module is free software; you can redistribute it and/or modify it
186         under the same terms as Perl itself.
187
188
189
190perl v5.8.8                       2006-12-07                    Email::Send(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT