[![Build Status](https://travis-ci.org/kan/p5-web-service-mailgun.svg?branch=master)](https://travis-ci.org/kan/p5-web-service-mailgun) [![Coverage Status](https://img.shields.io/coveralls/kan/p5-web-service-mailgun/master.svg?style=flat)](https://coveralls.io/r/kan/p5-web-service-mailgun?branch=master) # NAME WebService::Mailgun - API client for Mailgun ([https://mailgun.com/](https://mailgun.com/)) # SYNOPSIS ```perl use WebService::Mailgun; my $mailgun = WebService::Mailgun->new( api_key => '', domain => '', ); # send mail my $res = $mailgun->message({ from => 'foo@example.com', to => 'bar@example.com', subject => 'test', text => 'text', }); ``` # DESCRIPTION WebService::Mailgun is API client for Mailgun ([https://mailgun.com/](https://mailgun.com/)). # METHOD ## new(api\_key => $api\_key, domain => $domain, RaiseError => 0|1) Create mailgun object. ### RaiseError (default: 0) The RaiseError attribute can be used to force errors to raise exceptions rather than simply return error codes in the normal way. It is "off" by default. ## error return recent error message. ## error\_status return recent API result status\_line. ## message($args) Send email message. ```perl # send mail my $res = $mailgun->message({ from => 'foo@example.com', to => 'bar@example.com', subject => 'test', text => 'text', }); ``` [https://documentation.mailgun.com/en/latest/api-sending.html#sending](https://documentation.mailgun.com/en/latest/api-sending.html#sending) ## mime($args) Send a MIME message you build yourself, usually by using a library to create that MIME message. The `to` parameter needs to be passed as one of the arguments. Either the `file` or `message` parameter will also need to be passed. The `file` parameter should contain the path to the filename that holds the MIME message. The `message` parameter should contain either a string or a reference to a string that holds the MIME message: ```perl # send MIME message via a filename: my $res = $mailgun->message({ to => 'bar@example.com', file => '/path/to/filename.mime', }); # send MIME message via a string: use MIME::Entity; my $str = MIME::Entity->build( From => 'justin@dadamailproject.com', To => 'justin@dadamailproject.com', Subject => "Subject", Data => 'Messag4')->as_string; my $res = $mailgun->message({ to => 'bar@example.com', message => $str, }); # or send MIME message via a string ref: my $res = $mailgun->message({ to => 'bar@example.com', message => \$str, }); ``` [https://documentation.mailgun.com/en/latest/api-sending.html#sending](https://documentation.mailgun.com/en/latest/api-sending.html#sending) ## lists() Get list of mailing lists. ```perl # get mailing lists my $lists = $mailgun->lists(); # => ArrayRef of mailing list object. ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## add\_list($args) Add mailing list. ```perl # add mailing list my $res = $mailgun->add_list({ address => 'ml@example.com', # Mailing list address name => 'ml sample', # Mailing list name (Optional) description => 'sample', # description (Optional) access_level => 'members', # readonly(default), members, everyone }); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## list($address) Get detail for mailing list. ```perl # get mailing list detail my $data = $mailgun->list('ml@exmaple.com'); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## update\_list($address, $args) Update mailing list detail. ```perl # update mailing list my $res = $mailgun->update_list('ml@example.com' => { address => 'ml@example.com', # Mailing list address (Optional) name => 'ml sample', # Mailing list name (Optional) description => 'sample', # description (Optional) access_level => 'members', # readonly(default), members, everyone }); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## delete\_list($address) Delete mailing list. ```perl # delete mailing list my $res = $mailgun->delete_list('ml@example.com'); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## list\_members($address) Get members for mailing list. ```perl # get members my $res = $mailgun->list_members('ml@example.com'); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## add\_list\_member($address, $args) Add member for mailing list. ```perl # add member my $res = $mailgun->add_list_member('ml@example.com' => { address => 'user@example.com', # member address name => 'username', # member name (Optional) vars => '{"age": 34}', # member params(JSON string) (Optional) subscribed => 'yes', # yes(default) or no upsert => 'no', # no (default). if yes, update exists member }); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## add\_list\_members($address, $args) Adds multiple members for mailing list. ```perl use JSON::XS; # auto export 'encode_json' # add members my $res = $mailgun->add_list_members('ml@example.com' => { members => encode_json [ { address => 'user1@example.com' }, { address => 'user2@example.com' }, { address => 'user3@example.com' }, ], upsert => 'no', # no (default). if yes, update exists member }); # too simple my $res = $mailgun->add_list_members('ml@example.com' => { members => encode_json [qw/user1@example.com user2@example.com/], }); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## list\_member($address, $member\_address) Get member detail. ```perl # update member my $res = $mailgun->list_member('ml@example.com', 'user@example.com'); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## update\_list\_member($address, $member\_address, $args) Update member detail. ```perl # update member my $res = $mailgun->update_list_member('ml@example.com', 'user@example.com' => { address => 'user@example.com', # member address (Optional) name => 'username', # member name (Optional) vars => '{"age": 34}', # member params(JSON string) (Optional) subscribed => 'yes', # yes(default) or no }); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## delete\_list\_members($address, $member\_address) Delete member for mailing list. ```perl # delete member my $res = $mailgun->delete_list_member('ml@example.com' => 'user@example.com'); ``` [https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists](https://documentation.mailgun.com/en/latest/api-mailinglists.html#mailing-lists) ## event($args) Get event data. ```perl # get event data my ($events, $purl) = $mailgun->event({ event => 'stored', limit => 50 }); ``` [Events](https://documentation.mailgun.com/en/latest/api-events.html) ## get\_message\_from\_event($event) Get stored message. ```perl # get event data my ($events, $purl) = $mailgun->event({ event => 'stored' }); my $msg = $mailgun->get_message_from_event($events->[0]); ``` [Stored Message](https://documentation.mailgun.com/en/latest/api-sending.html#retrieving-stored-messages) # Event Pooling event method return previous url. it can use for fetch event. ```perl # event Pooling my ($events, $purl) = $mailgun->event({ event => 'stored', begin => localtime->epoch() }); // do something ... $events = $mailgun->event($purl); // ... ``` [Event Polling](https://documentation.mailgun.com/en/latest/api-events.html#event-polling) # TODO this API not implement yet. - [Domains](https://documentation.mailgun.com/en/latest/api-domains.html) - [Stats](https://documentation.mailgun.com/en/latest/api-stats.html) - [Tags](https://documentation.mailgun.com/en/latest/api-tags.html) - [Suppressions](https://documentation.mailgun.com/en/latest/api-suppressions.html) - [Routes](https://documentation.mailgun.com/en/latest/api-routes.html) - [Webhooks](https://documentation.mailgun.com/en/latest/api-webhooks.html) - [Email Validation](https://documentation.mailgun.com/en/latest/api-email-validation.html) # SEE ALSO [WWW::Mailgun](https://metacpan.org/pod/WWW%3A%3AMailgun), [https://documentation.mailgun.com/en/latest/](https://documentation.mailgun.com/en/latest/) # LICENSE Copyright (C) Kan Fushihara. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. # AUTHOR Kan Fushihara