NAME

WebService::Mailgun - API client for Mailgun (https://mailgun.com/)

SYNOPSIS

use WebService::Mailgun;

my $mailgun = WebService::Mailgun->new(
    api_key => '<YOUR_API_KEY>',
    domain => '<YOUR_MAIL_DOMAIN>',
);

# send mail
my $res = $mailgun->message({
    from    => 'foo@example.com',
    to      => 'bar@example.com',
    subject => 'test',
    text    => 'text',
}) or die $mailgun->error;

DESCRIPTION

WebService::Mailgun is a client for the Mailgun API (https://mailgun.com/): sending messages (also in MIME format), mailing lists and their members, events, stored messages and templates.

Each method sends one request, or a series of them for the methods that return every page of a list, and returns the response decoded from JSON.

Errors

When a request fails, the method returns undef (an empty list in list context), and error and error_status tell why. With RaiseError => 1, it warns with the error message and dies with the status line instead.

my $res = $mailgun->message($args)
    or die sprintf '%s: %s', $mailgun->error_status, $mailgun->error;

The methods that return every page ("Lists of every page") do not return undef: they stop at the page that failed and return the items fetched so far. Without RaiseError, a failure there shows only in error, which keeps the message of the last failure until the next one.

Lists of every page

lists, list_members and event follow paging.next until a page has no items, and return two values: an array reference of all the items, and the paging.next URL of that empty page as a URI, where the items that come later will be (for event, see "Event Polling"). When a request fails, the second value is the URL of the page that failed instead, so that the rest can be fetched from there. Take the items in list context:

my ($lists) = $mailgun->lists();
my ($events, $next) = $mailgun->event({ event => 'stored', ascending => 'yes' });

In scalar context they return the URL, not the items.

METHODS

new(api_key => $api_key, domain => $domain, region => "us"|"eu", RaiseError => 0|1)

Create a WebService::Mailgun object.

RaiseError (default: 0)

Die when a request fails, instead of returning undef (see "Errors").

region (default: "us")

The region the domain belongs to: us or eu. Any other value dies when a request is made.

error

The error message of the last request that failed.

error_status

The status line (401 Unauthorized, say) of the last request that failed.

message($args)

Send email message.

# send mail
my $res = $mailgun->message({
    from    => 'foo@example.com',
    to      => 'bar@example.com',
    subject => 'test',
    text    => 'text',
});

To pass the same key more than once (several attachments, say), pass an array reference of key-value pairs instead of a hash reference:

my $res = $mailgun->message([
    from       => 'foo@example.com',
    to         => 'bar@example.com',
    subject    => 'test',
    text       => 'text',
    attachment => ['/path/to/a.pdf'],
    attachment => ['/path/to/b.pdf'],
]);

Send an email

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:

# send MIME message via a filename:
my $res = $mailgun->mime({
    to   => 'bar@example.com',
    file => '/path/to/filename.mime',
});

# send MIME message via a string:
use MIME::Entity;
my $str = MIME::Entity->build(
    From    => 'foo@example.com',
    To      => 'bar@example.com',
    Subject => 'Subject',
    Data    => 'Message',
)->as_string;

my $res = $mailgun->mime({
    to      => 'bar@example.com',
    message => $str,
});

# or send MIME message via a string ref:
my $res = $mailgun->mime({
    to      => 'bar@example.com',
    message => \$str,
});

mime() changes the hash reference it is given: message becomes an array reference holding the path of a temporary file (or of file, which is removed). Pass a new hash reference for each call.

Send a message in MIME format

lists()

Get list of mailing lists.

# get mailing lists (every page; see "Lists of every page")
my ($lists) = $mailgun->lists();
# => ArrayRef of mailing list object.

Get mailing lists

add_list($args)

Add mailing list.

# 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
});

Create a mailing list

list($address)

Get detail for mailing list.

# get mailing list detail
my $data = $mailgun->list('ml@example.com');

Get a mailing list

update_list($address, $args)

Update mailing list detail.

# 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
});

Update a mailing list

delete_list($address)

Delete mailing list.

# delete mailing list
my $res = $mailgun->delete_list('ml@example.com');

Delete a mailing list

list_members($address)

Get members for mailing list.

# get members (every page; see "Lists of every page")
my ($members) = $mailgun->list_members('ml@example.com');

Get members of a mailing list

add_list_member($address, $args)

Add member for mailing list.

# 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
});

Add a member to a mailing list

add_list_members($address, $args)

Adds multiple members for mailing list.

use JSON; # 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
});

# or just the addresses
my $res = $mailgun->add_list_members('ml@example.com' => {
    members => encode_json [qw/user1@example.com user2@example.com/],
});

Add members to a mailing list

list_member($address, $member_address)

Get member detail.

# get member
my $member = $mailgun->list_member('ml@example.com', 'user@example.com');

Get a member of a mailing list

update_list_member($address, $member_address, $args)

Update member detail.

# 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
});

Update a member of a mailing list

delete_list_member($address, $member_address)

Delete member for mailing list.

# delete member
my $res = $mailgun->delete_list_member('ml@example.com' => 'user@example.com');

Delete a member of a mailing list

event($args|$url)

Get event data. $args is a hash reference of the query. In its place $url (a URI or a string) is fetched as it is, such as the second value an earlier call returned (see "Event Polling"); it must be an https URL on the API's host, or event dies.

# get event data (every page; see "Lists of every page")
my ($events, $next) = $mailgun->event({ event => 'stored', limit => 50 });

Get events

get_message_from_event($event)

Get stored message. $event must be a stored event; any other event dies.

# get event data
my ($events) = $mailgun->event({ event => 'stored' });
my $msg = $mailgun->get_message_from_event($events->[0]);

Retrieve a stored email

add_template($args)

Add a template. Like message, it takes a hash reference or an array reference of key-value pairs.

# add template
my $res = $mailgun->add_template({
    name        => 'welcome',     # Template name
    template    => 'Hello!',      # Template data
    engine      => 'handlebars',  # Template engine (optional)
    description => 'xyz',         # Description of template (optional)
    tag         => '2.0' ,        # Version tag (optional)
    comment     => 'Test',        # Version comment (optional)
});

Create a template

delete_templates()

Delete all templates of the domain.

my $res = $mailgun->delete_templates();

Delete all templates

delete_template($name)

Delete a template.

my $res = $mailgun->delete_template($name);

Delete a template

Event Polling

The second value event returns is the paging.next URL of the empty page it stopped at, as a URI with the API key set. Pass it back to event in place of the query, and it returns the events stored since the last call, and the URL to use the next time:

use Time::Piece;

my ($events, $next) = $mailgun->event({
    event     => 'stored',
    begin     => localtime->epoch - 30 * 60,
    ascending => 'yes',
});
while (1) {
    # do something with @$events ...
    sleep 60;
    ($events, $next) = $mailgun->event($next);
}

Use ascending => 'yes', so that the URL points forward in time.

Mailgun may store an event some time after it happens. Such an event can be dated before events already fetched, and the URL does not return it. If every event matters, fetch a time range again once it is old enough (Mailgun's documentation suggests half an hour), and drop the events whose id was seen already.

Event Polling

TODO

These APIs are not implemented yet.

SEE ALSO

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 <kan.fushihara@gmail.com>