Email::Send(3pm)

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

NAME

6       Email::Send - Simply Sending Email
7

WAIT! ACHTUNG!

9       Email::Send is going away... well, not really going away, but it's
10       being officially marked "out of favor."  It has API design problems
11       that make it hard to usefully extend and rather than try to deprecate
12       features and slowly ease in a new interface, we've released
13       Email::Sender which fixes these problems and others.  As of today,
14       2008-12-19, Email::Sender is young, but it's fairly well-tested.
15       Please consider using it instead for any new work.
16

SYNOPSIS

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

DESCRIPTION

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

PERL EMAIL PROJECT

184       This module is maintained by the Perl Email Project.
185
186       <http://emailproject.perl.org/wiki/Email::Send>
187

AUTHOR

189       Current maintainer: Ricardo SIGNES, <rjbs@cpan.org>.
190
191       Original author: Casey West, <casey@geeknest.com>.
192

COPYRIGHT

194         Copyright (c) 2005 Casey West.  All rights reserved.
195         This module is free software; you can redistribute it and/or modify it
196         under the same terms as Perl itself.
197
198
199
200perl v5.36.0                      2023-01-20                    Email::Send(3)