/ 
WWW-Postmark-0.1
River stage zero No dependents
/ WWW::Postmark

NAME

WWW::Postmark - API for the Postmark mail service for web applications.

VERSION

version 0.1

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 (right now first 1,000 emails are free), 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).

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.

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.

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.

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>

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:

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.