337 lines (248 sloc) 6.89 KB

API documentation

This page will document the API classes and ways to properly use the API. These resources will eventually move to the official documentation at

Other relevant documentation pages might be:

Domain API

Get a list of all domains


Show a single domains


Verify a domain


Create a new domain

$mailgun->domains()->create('', 'password', 'disable', '*');

Delete a domain


Get credentials for a domain


Create credentials for a domain

$mailgun->domains()->createCredential('', 'login', 'password');

Update credentials for a domain

$mailgun->domains()->updateCredential('', 'login', 'password');

Delete credentials for a domain

$mailgun->domains()->deleteCredential('', 'login');

Get connection for a domain


Update connection for a domain

$mailgun->domains()->updateConnection('', true, false);

Event API

Get all events for a domain


Message API

Send a message

$parameters = [
    'from'    => '', 
    'to'      => '', 
    'subject' => 'The PHP SDK is awesome!', 
    'text'    => 'It is so simple to send a message.'
$mailgun->messages()->send('', $parameters);

Send a message with Mime

Below in an example how to create a Mime message with SwiftMailer.

$message = \Swift_Message::newInstance('Mail Subject');
$message->setFrom(['' => 'Example Inc']);
$message->setTo(['' => 'User 0', '' => 'User 1']);
// $message->setBcc(''); Do not do this, BCC will be visible for all receipients if you do. 

$messageBody = 'Look at the <b>fancy</b> HTML body.';
$message->setBody($messageBody, 'text/html');

// We need all "tos". Incluce the BCC here.
$to = ['', '', '', '']

// Send the message
$mailgun->messages()->sendMime('', $to, $message->toString());

Show a stored message

If you got an URL to a stored message you may get the details by:

$url = // ...

Route API

Show all routes


Show a routes

Get a route by its ID


Create a route

$expression = "match_recipient('.*')";
$actions = ["forward('')"];
$description = 'Test route';

$mailgun->routes()->create($expression, $actions, $description);

Update a route

$expression = "match_recipient('.*')";
$actions = ["forward('')"];
$description = 'Test route';

$mailgun->routes()->update(4711, $expression, $actions, $description);

Delete a route


Stats API

Get total stats for a domain


Get all stats for a domain


Suppression API

The suppression API consists of 3 parts; Bounce, Complaint and Unsubscribe.

Bounce API

Get all bounces


Show bounces for a specific address

$mailgun->suppressions()->bounces()->show('', '');

Create a bounce

$mailgun->suppressions()->bounces()->create('', '');

Delete a bounce

$mailgun->suppressions()->bounces()->delete('', '');

Delete all bounces


Complaint API

Get all complaints


Show complaints for a specific address

$mailgun->suppressions()->complaints()->show('', '');

Create a complaint

$mailgun->suppressions()->complaints()->create('', '');

Delete a complaint

$mailgun->suppressions()->complaints()->delete('', '');

Delete all complaints


Unsubscribe API

Get all unsubscriptions


Show unsubscriptions for a specific address

$mailgun->suppressions()->unsubscribes()->show('', '');

Create an unsubscription

$mailgun->suppressions()->unsubscribes()->create('', '');

Delete an unsubscription

$mailgun->suppressions()->unsubscribes()->delete('', '');

Delete all unsubscriptions



Show all tags


Show a single tag

$mailgun->tags()->show('', 'foo');

Update a tag

$mailgun->tags()->update('', 'foo', 'description');

Show stats for a tag

$mailgun->tags()->stats('', 'foo');

Delete a tag

$mailgun->tags()->delete('', 'foo');

Webhook API

Verify webhook signature

$timestamp = $_POST['timestamp'];
$token = $_POST['token'];
$signature = $_POST['signature'];

$mailgun = Mailgun::create('my_api_key');
$valid = $mailgun->webhooks()->verifyWebhookSignature($timestamp, $token, $signature);

if (!$valid) {
    // Create a 403 response

// The signature is valid

Show all webhooks


Show a single webhooks

$mailgun->webhooks()->show('', 'accept');

Create a webhooks

$mailgun->webhooks()->create('', 'accept', '');

Update a webhooks

$mailgun->webhooks()->update('', 4711, '');

Delete a webhooks

$mailgun->webhooks()->delete('', 4711);