| 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__ |