1Email::Sender::Manual::UQsueirckCSotnatrrti(b3u)ted PerlEmDaoiclu:m:eSnetnadteiro:n:Manual::QuickStart(3)
2
3
4

NAME

6       Email::Sender::Manual::QuickStart - how to start using Email::Sender
7       right now
8

VERSION

10       version 2.600
11

PERL VERSION

13       This library should run on perls released even a long time ago.  It
14       should work on any version of perl released in the last five years.
15
16       Although it may work on older versions of perl, no guarantee is made
17       that the minimum required version will not be increased.  The version
18       may be increased for any reason, and there is no promise that patches
19       will be accepted to lower the minimum required perl.
20

QUICK START

22   Let's Send Some Mail!
23       No messing around, let's just send some mail.
24
25         use strict;
26         use Email::Sender::Simple qw(sendmail);
27         use Email::MIME;
28
29         # You can make an email object in lots of ways.  Pick one you like!
30         my $email = Email::MIME->create(...);
31
32         sendmail($email);
33
34       That's it.  Your message goes out into the internet and tries to get
35       delivered to "x.ample@example.com".
36
37       In the example above, $email could be an Email::MIME object, a
38       MIME::Entity, a string containing an email message, or one of several
39       other types of input.  If "Email::Abstract" can understand a value, it
40       can be passed to Email::Sender::Simple.  Email::Sender::Simple tries to
41       make a good guess about how to send the message.  It will usually try
42       to use the sendmail program on unix-like systems and to use SMTP on
43       Windows.  You can specify a transport, if you need to, but normally
44       that shouldn't be an issue.  (See "Picking a Transport", though, for
45       more information.)
46
47       Also note that we imported and used a "sendmail" routine in the example
48       above.  This is exactly the same as saying:
49
50         Email::Sender::Simple->send($email);
51
52       ...but it's a lot easier to type.  You can use either one.
53
54       envelope information
55
56       We didn't have to tell Email::Sender::Simple where to send the message.
57       If you don't specify recipients, it will use all the email addresses it
58       can find in the To and Cc headers by default.  It will use
59       Email::Address::XS to parse those fields.  Similarly, if no sender is
60       specified, it will use the first address found in the From header.
61
62       In most email transmission systems, though, the headers are not by
63       necessity tied to the addresses used as the sender and recipients.  For
64       example, your message header might say "From: mailing-list@example.com"
65       while your SMTP client says "MAIL FROM:<verp-1234@lists.example.com>".
66       This is a powerful feature, and is necessary for many email
67       application.  Being able to set those distinctly is important, and
68       Email::Sender::Simple lets you do this:
69
70         sendmail($email, { to => [ $to_1, $to_2 ], from => $sender });
71
72       in case of error
73
74       When the message is sent successfully (at least on to its next hop),
75       "sendmail" will return a true value -- specifically, an
76       Email::Sender::Success object.  This object only rarely has much use.
77       What's more useful is what happens if the message can't be sent.
78
79       If there is an error sending the message, an exception will be thrown.
80       It will be an object belonging to the class Email::Sender::Failure.
81       This object will have a "message" attribute describing the nature of
82       the failure.  There are several specialized forms of failure, like
83       Email::Sender::Failure::Multi, which is thrown when more than one error
84       is encountered when trying to send.  You don't need to know about these
85       to use Email::Sender::Simple, though.  All you need to know is that
86       "sendmail" returns true on success and dies on failure.
87
88       If you'd rather not have to catch exceptions for failure to send mail,
89       you can use the "try_to_send" method, which can be imported as
90       "try_to_sendmail".  This method will return just false on failure to
91       send mail.
92
93       For example:
94
95         Email::Sender::Simple->try_to_send($email, { ... });
96
97         use Email::Sender::Simple qw(try_to_sendmail);
98         try_to_sendmail($email, { ... });
99
100       Some Email::Sender transports can signal success if some, but not all,
101       recipients could be reached.  Email::Sender::Simple does its best to
102       ensure that this never happens.  When you are using
103       Email::Sender::Simple, mail should either be sent or not.  Partial
104       success should never occur.
105
106   Picking a Transport
107       passing in your own transport
108
109       If Email::Sender::Simple doesn't pick the transport you want, or if you
110       have more specific needs, you can specify a transport in several ways.
111       The simplest is to build a transport object and pass it in.  You can
112       read more about transports elsewhere.  For now, we'll just assume that
113       you need to send mail via SMTP on an unusual port.  You can send mail
114       like this:
115
116         my $transport = Email::Sender::Transport::SMTP->new({
117           host => 'smtp.example.com',
118           port => 2525,
119         });
120
121         sendmail($email, { transport => $transport });
122
123       Now, instead of guessing at what transport to use,
124       Email::Sender::Simple will use the one you provided.  This transport
125       will have to be specified for each call to "sendmail", so you might
126       want to look at other options, which follow.
127
128       specifying transport in the environment
129
130       If you have a program that makes several calls to
131       Email::Sender::Simple, and you need to run this program using a
132       different mailserver, you can set environment variables to change the
133       default.  For example:
134
135         $ export EMAIL_SENDER_TRANSPORT=SMTP
136         $ export EMAIL_SENDER_TRANSPORT_host=smtp.example.com
137         $ export EMAIL_SENDER_TRANSPORT_port=2525
138
139         $ perl your-program
140
141       It is important to note that if you have set the default transport by
142       using the environment, no subsequent "transport" args to "sendmail"
143       will be respected.  If you set the default transport via the
144       environment, that's it.  Everything will use that transport.  (Also,
145       note that while we gave the host and port arguments above in lower
146       case, the casing of arguments in the environment is flattened to
147       support systems where environment variables are of a fixed case.  So,
148       "EMAIL_SENDER_TRANSPORT_PORT" would also work.
149
150       This is extremely valuable behavior, as it allows you to audit every
151       message that would be sent by a program by running something like this:
152
153         $ export EMAIL_SENDER_TRANSPORT=Maildir
154         $ perl your-program
155
156       In that example, any message sent via Email::Sender::Simple would be
157       delivered to a maildir in the current directory.
158
159       subclassing to change the default transport
160
161       If you want to use a library that will behave like
162       Email::Sender::Simple but with a different default transport, you can
163       subclass Email::Sender::Simple and replace the
164       "build_default_transport" method.
165
166   Testing
167       Email::Sender::Simple makes it very, very easy to test code that sends
168       email.  The simplest way is to do something like this:
169
170         use Test::More;
171         BEGIN { $ENV{EMAIL_SENDER_TRANSPORT} = 'Test' }
172         use YourCode;
173
174         YourCode->run;
175
176         my @deliveries = Email::Sender::Simple->default_transport->deliveries;
177
178       Now you've got an array containing every delivery performed through
179       Email::Sender::Simple, in order.  Because you set the transport via the
180       environment, no other code will be able to force a different transport.
181
182       When testing code that forks, Email::Sender::Transport::SQLite can be
183       used to allow every child process to deliver to a single, easy to
184       inspect destination database.
185
186   Hey, where's my Bcc support?
187       A common question is "Why doesn't Email::Sender::Simple automatically
188       respect my Bcc header?"  This is often combined with, "Here is a patch
189       to 'fix' it."  This is not a bug or oversight. Bcc is being ignored
190       intentionally for now because simply adding the Bcc addresses to the
191       message recipients would not produce the usually-desired behavior.
192
193       For example, here is a set of headers:
194
195         From: sender@example.com
196         To:   to_rcpt@example.com
197         Cc:   cc_rcpt@example.com
198         Bcc:  the_boss@example.com
199
200       In this case, we'd expect the message to be delivered to three people:
201       to_rcpt, cc_rcpt, and the_boss.  This is why it's often suggested that
202       the Bcc header should be a source for envelope recipients.  In fact,
203       though, a message with a Bcc header should probably be delivered only
204       to the Bcc recipients.  The "B" in Bcc means "blind."  The other
205       recipients should not see who has been Bcc'd.  This means you want to
206       send two messages:  one to to_rcpt and cc_rcpt, with no Bcc header
207       present; and another to the_boss only, with the Bcc header.  If you
208       just pick up Bcc addresses as recipients, everyone will see who was
209       Bcc'd.
210
211       Email::Sender::Simple promises to send messages atomically.  That is:
212       it won't deliver to only some of the recipients, and not to others.
213       That means it can't automatically detect the Bcc header and make two
214       deliveries.  There would be a possibility for the second to fail after
215       the first succeeded, which would break the promise of a pure failure or
216       success.
217
218       The other strategy for dealing with Bcc is to remove the Bcc header
219       from the message and then inject the message with an envelope including
220       the Bcc addresses.  The envelope information will not be visible to the
221       final recipients, so this is safe.  Unfortunately, this requires
222       modifying the message, and Email::Sender::Simple should not be altering
223       the mutable email object passed to it.  There is no "clone" method on
224       Email::Abstract, so it cannot just build a clone and modify that,
225       either.  When such a method exists, Bcc handling may be possible.
226
227       Example Bcc Handling
228
229       If you want to support the Bcc header now, it is up to you to deal with
230       how you want to munge the mail and inject the (possibly) munged copies
231       into your outbound mailflow.  It is not reasonable to suggest that
232       Email::Sender::Simple do this job.
233
234       Example 1: Explicitly set the envelope recipients for Bcc recipients
235
236       Create the email without a Bcc header, send it to the Bcc users
237       explicitly and then send it to the To/Cc users implicitly.
238
239         my $message = create_email_mime_msg;  # <- whatever you do to get the message
240
241         $message->header_set('bcc');          # delete the Bcc header before sending
242         sendmail($message, { to => $rcpt });  # send to explicit Bcc address
243         sendmail($message);                   # and then send as normal
244
245       Example 2: Explicitly set the envelope recipients for all recipients
246
247       You can make a single call to "sendmail" by pulling all the recipient
248       addresses from the headers yourself and specifying all the envelope
249       recipients once.  Again, delete the Bcc header before the message is
250       sent.
251

SEE ALSO

253   This is awesome!  Where can I learn more?
254       Have a look at Email::Sender::Manual, where all the manual's documents
255       are listed.  You can also look at the documentation for
256       Email::Sender::Simple and the various Email::Sender::Transport classes.
257

AUTHOR

259       Ricardo Signes <cpan@semiotic.systems>
260
262       This software is copyright (c) 2022 by Ricardo Signes.
263
264       This is free software; you can redistribute it and/or modify it under
265       the same terms as the Perl 5 programming language system itself.
266
267
268
269perl v5.36.0                      2023-01-2E0mail::Sender::Manual::QuickStart(3)
Impressum