GitHub - mzehrer/WWW-Postmark: API for the Postmark mail service (postmarkapp.com) for web applications.

Branches Tags

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
lib/WWW		lib/WWW
t		t
.gitignore		.gitignore
Changes		Changes
MANIFEST.SKIP		MANIFEST.SKIP
README		README
dist.ini		dist.ini

Repository files navigation

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.