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'],
]);
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.
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.
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
});
list($address)
Get detail for mailing list.
# get mailing list detail
my $data = $mailgun->list('ml@example.com');
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
});
delete_list($address)
Delete mailing list.
# delete mailing list
my $res = $mailgun->delete_list('ml@example.com');
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');
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/],
});
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_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]);
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)
});
delete_templates()
Delete all templates of the domain.
my $res = $mailgun->delete_templates();
delete_template($name)
Delete a template.
my $res = $mailgun->delete_template($name);
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.
TODO
These APIs are not implemented yet.
Suppressions (Bounces, Unsubscribes, Complaints, Allowlist)
Templates (only creating and deleting are implemented)
SEE ALSO
WWW::Mailgun, another client for the Mailgun API
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>