עידו פרלמוטר (Ido Perlmuter) > WWW-Postmark > WWW::Postmark

Download:
WWW-Postmark-0.7.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.7   Source  

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).

Note that in order to use SSL, HTTP::Tiny requires certain dependencies to be installed. See "SSL SUPPORT" in HTTP::Tiny for more information.

send( %params )

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 hash reference of Postmark's response is returned (refer to the relevant Postmark documentation); otherwise, this method will croak with an approriate error message (see "DIAGNOSTICS" for a full list).

The following keys are required when using this method:

You can optionally supply the following parameters as well:

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.

DIAGNOSTICS ^

The following exceptions are thrown by this module:

"You have not provided a Postmark API token, you cannot send emails"

This means you haven't provided the new() subroutine your Postmark API token. Using the Postmark API requires an API token, received when registering to their service via their website.

"You must provide a mail subject."

This error means you haven't given the send() method a subject for your email message. Messages sent with this module must have a subject.

"You must provide a mail body."

This error means you haven't given the send() method a body for your email message. Messages sent with this module must have content.

"You must provide a valid 'from' address in the format 'address\@domain.tld', or 'Your Name <address\@domain.tld>'."

This error means the address (or one of the addresses) you're trying to send an email to with the send() method is not a valid email address (in the sense that it cannot be an email address, not in the sense that the email address does not exist (For example, "asdf" is not a valid email address).

"You must provide a valid reply-to address, in the format 'address\@domain.tld', or 'Some Name <address\@domain.tld>'."

This error, when providing the reply-to parameter to the send() method, means the reply-to value is not a valid email address.

"You must provide a valid '%s' address or addresses, in the format 'address\@domain.tld', or 'Some Name <address\@domain.tld>'. If you're sending to multiple addresses, separate them with commas. You can send up to 20 maximum addresses."

Like the above two error messages, but for other email fields such as cc and bcc.

"Failed sending message: %s"

This error is thrown when sending an email fails. The error message should include the actual reason for the failure. Usually, the error is returned by the Postmark API. For a list of errors returned by Postmark and their meaning, take a look at http://developer.postmarkapp.com/developer-build.html.

"Unknown Postmark error code %s"

This means Postmark returned an error code that this module does not recognize. The error message should include the error code. If you find that error code in http://developer.postmarkapp.com/developer-build.html, it probably means this is a new error code this module does not know about yet, so please open an appropriate bug report.

"Unknown HTTP error code %s."

This means the Postmark API returned an unexpected HTTP status code. The error message should include the status code returned.

"You must provide the raw email text to spam_score()."

This error means you haven't passed the spam_score() method the requried raw email text.

"Postmark spam score API returned error: %s"

This error means the spam score API failed parsing your raw email text. The error message should include the actual reason for the failure. This would be an expected API error. Unexpected API errors will be thrown with the next error message.

"Failed determining spam score: %s"

This error means the spam score API returned an HTTP error. The error message should include the actual error message returned.

CONFIGURATION AND ENVIRONMENT ^

WWW::Postmark requires no configuration files or environment variables.

DEPENDENCIES ^

WWW::Postmark depends on the following CPAN modules:

WWW::Postmark recommends JSON::XS for parsing JSON (the Postmark API is JSON based). If installed, JSON will automatically load JSON::XS instead. For SSL support, IO::Socket::SSL and Net::SSLeay are also recommended.

INCOMPATIBILITIES WITH OTHER MODULES ^

None reported.

BUGS AND LIMITATIONS ^

No bugs have been reported.

Please report any bugs or feature requests to bug-WWW-Postmark@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Postmark.

AUTHOR ^

Ido Perlmuter <ido@ido50.net>

With help from: Casimir Loeber.

LICENSE AND COPYRIGHT ^

Copyright (c) 2010-2014, Ido Perlmuter ido@ido50.net.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either version 5.8.1 or any later version. See perlartistic and perlgpl.

The full text of the license can be found in the LICENSE file included with this module.

DISCLAIMER OF WARRANTY ^

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

syntax highlighting: