blib/lib/Email/Sender/Manual/QuickStart.pm untested

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