forked from ido50/WWW-Postmark
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
188 lines (132 loc) · 6.75 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
NAME
WWW::Postmark - API for the Postmark mail service for web applications.
SYNOPSIS
use WWW::Postmark;
my $api = WWW::Postmark->new('api_token');
# or, if you want to use SSL
my $api = WWW::Postmark->new('api_token', 1);
# send an email
$api->send(from => 'me@domain.tld', to => 'you@domain.tld, them@domain.tld',
subject => 'an email message', body => "hi guys, what's up?");
DESCRIPTION
The WWW::Postmark module provides a simple API for the Postmark web
service, that provides email sending facilities for web applications.
Postmark is located at <http://postmarkapp.com>. It is a paid service
that charges according the amount of emails you send, and requires
signing up in order to receive an API token.
You can send emails either through HTTP or HTTPS with SSL encryption.
You can send your emails to multiple recipients at once (but there's a
20 recipients limit). If WWW::Postmark receives a successful response
from the Postmark service, it will return a true value; otherwise it
will die.
To make it clear, Postmark is not an email marketing service for sending
email campaigns or newsletters to multiple subscribers at once. It's
meant for sending emails from web applications in response to certain
events, like someone signing up to your website.
Postmark provides a test API token that doesn't really send the emails.
The token is 'POSTMARK_API_TEST', and you can use it for testing
purposes (the tests in this distribution use this token).
Besides sending emails, this module also provides support for Postmark's
spam score API, which allows you to get a SpamAssassin report for an
email message. See documentation for the "spam_score()" method for more
info.
METHODS
new( [ $api_token, $use_ssl] )
Creates a new instance of this class, with a Postmark API token that
you've received from the Postmark app. By default, requests are made
through HTTP; if you want to send them with SSL encryption, pass a true
value for $use_ssl.
If you do not provide an API token, you will only be able to use
Postmark's spam score API (you will not be able to send emails).
send( from => 'you@mail.com', to => 'them@mail.com', subject =>
'An email message', body => $message_body, [ cc => 'someone@mail.com',
bcc => 'otherone@mail.com, anotherone@mail.com', tag => 'sometag',
reply_to => 'do-not-reply@mail.com' ] )
Receives a hash representing the email message that should be sent and
attempts to send it through the Postmark service. If the message was
successfully sent, a true value is returned; otherwise, this method will
croak with an approriate error message (see ""ERRORS" for a full list).
The following keys are required when using this method:
* from
The email address of the sender. Either pass the email address
itself in the format 'mail_address@domain.tld' or also provide a
name, like 'My Name <mail_address@domain.tld>'.
* to
The email address(es) of the recipient(s). You can use both formats
as in 'to', but here you can give multiple addresses. Use a comma to
separate them. Note, however, that Postmark limits this to 20
recipients and sending will fail if you attempt to send to more than
20 addresses.
* subject
The subject of your message.
* body
The body of your message. This could be plain text, or HTML. If you
want to send HTML, be sure to open with '<html>' and close with
'</html>'. This module will look for these tags in order to find out
whether you're sending a text message or an HTML message.
Since version 0.3, however, you can explicitly specify the type of
your message, and also send both plain text and HTML. To do so, use
the "html" and/or "text" attributes. Their presence will override
"body".
* html
Instead of using "body" you can also specify the HTML content
directly.
* text
... or the plain text part of the email.
You can optionally supply the following parameters as well:
* cc, bcc
Same rules as the 'to' parameter.
* tag
Can be used to label your mail messages according to different
categories, so you can analyze statistics of your mail sendings
through the Postmark service.
* reply_to
Will force recipients of your email to send their replies to this
mail address when replying to your email.
spam_score( $raw_email, [ $options ] )
Use Postmark's SpamAssassin API to determine the spam score of an email
message. You need to provide the raw email text to this method, with all
headers intact. If $options is 'long' (the default), this method will
return a hash-ref with a 'report' key, containing the full SpamAssasin
report, and a 'score' key, containing the spam score. If $options is
'short', only the spam score will be returned (directly, not in a
hash-ref).
If the API returns an error, this method will croak.
Note that the SpamAssassin API is currently HTTP only, there is no HTTPS
interface, so the "use_ssl" option to the "new()" method is ignored
here.
For more information about this API, go to
<http://spamcheck.postmarkapp.com>.
INTERNAL METHODS
The following methods are only to be used internally.
_validate_recipients
_recipient_error( $field )
_analyze_response( $res )
AUTHOR
Ido Perlmuter, "<ido at ido50 dot net>"
ACKNOWLEDGMENTS
Ask Bjørn Hansen, for submitting a patch.
BUGS
Please report any bugs or feature requests to "bug-www-postmark at
rt.cpan.org", or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Postmark>. I will be
notified, and then you'll automatically be notified of progress on your
bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WWW::Postmark
You can also look for information at:
* RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Postmark>
* AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/WWW-Postmark>
* CPAN Ratings
<http://cpanratings.perl.org/d/WWW-Postmark>
* Search CPAN
<http://search.cpan.org/dist/WWW-Postmark/>
LICENSE AND COPYRIGHT
Copyright 2010 Ido Perlmuter.
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.