Permalink
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 https://documentation.mailgun.com.

Other relevant documentation pages might be:

Domain API

Get a list of all domains

$mailgun->domains()->index();

Show a single domains

$mailgun->domains()->show('example.com');

Verify a domain

$mailgun->domains()->verify('example.com');

Create a new domain

$mailgun->domains()->create('new.example.com', 'password', 'disable', '*');

Delete a domain

$mailgun->domains()->delete('example.com');

Get credentials for a domain

$mailgun->domains()->credentials('example.com');

Create credentials for a domain

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

Update credentials for a domain

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

Delete credentials for a domain

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

Get connection for a domain

$mailgun->domains()->connection('example.com');

Update connection for a domain

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

Event API

Get all events for a domain

$mailgun->events()->get('example.com');

Message API

Send a message

$parameters = [
    'from'    => 'bob@example.com', 
    'to'      => 'sally@example.com', 
    'subject' => 'The PHP SDK is awesome!', 
    'text'    => 'It is so simple to send a message.'
];
$mailgun->messages()->send('example.com', $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(['from@exemple.com' => 'Example Inc']);
$message->setTo(['user0gmail.com' => 'User 0', 'user1@hotmail.com' => 'User 1']);
// $message->setBcc('admin@example.com'); Do not do this, BCC will be visible for all receipients if you do. 
$message->setCc('invoice@example.com');

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

// We need all "tos". Incluce the BCC here.
$to = ['admin@example.com', 'user0gmail.com', 'user1@hotmail.com', 'invoice@example.com']

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

Show a stored message

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

$url = // ...
$mailgun->messages()->show($url);

Route API

Show all routes

$mailgun->routes()->index();

Show a routes

Get a route by its ID

$mailgun->routes()->show(4711);

Create a route

$expression = "match_recipient('.*@gmail.com')";
$actions = ["forward('alice@example.com')"];
$description = 'Test route';

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

Update a route

$expression = "match_recipient('.*@gmail.com')";
$actions = ["forward('alice@example.com')"];
$description = 'Test route';

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

Delete a route

$mailgun->routes()->delete(4711);

Stats API

Get total stats for a domain

$mailgun->stats()->total('example.com');

Get all stats for a domain

$mailgun->stats()->all('example.com');

Suppression API

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

Bounce API

Get all bounces

$mailgun->suppressions()->bounces()->index('example.com');

Show bounces for a specific address

$mailgun->suppressions()->bounces()->show('example.com', 'alice@gmail.com');

Create a bounce

$mailgun->suppressions()->bounces()->create('example.com', 'alice@gmail.com');

Delete a bounce

$mailgun->suppressions()->bounces()->delete('example.com', 'alice@gmail.com');

Delete all bounces

$mailgun->suppressions()->bounces()->deleteAll('example.com');

Complaint API

Get all complaints

$mailgun->suppressions()->complaints()->index('example.com');

Show complaints for a specific address

$mailgun->suppressions()->complaints()->show('example.com', 'alice@gmail.com');

Create a complaint

$mailgun->suppressions()->complaints()->create('example.com', 'alice@gmail.com');

Delete a complaint

$mailgun->suppressions()->complaints()->delete('example.com', 'alice@gmail.com');

Delete all complaints

$mailgun->suppressions()->complaints()->deleteAll('example.com');

Unsubscribe API

Get all unsubscriptions

$mailgun->suppressions()->unsubscribes()->index('example.com');

Show unsubscriptions for a specific address

$mailgun->suppressions()->unsubscribes()->show('example.com', 'alice@gmail.com');

Create an unsubscription

$mailgun->suppressions()->unsubscribes()->create('example.com', 'alice@gmail.com');

Delete an unsubscription

$mailgun->suppressions()->unsubscribes()->delete('example.com', 'alice@gmail.com');

Delete all unsubscriptions

$mailgun->suppressions()->unsubscribes()->deleteAll('example.com');

Tag API

Show all tags

$mailgun->tags()->index('example.com');

Show a single tag

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

Update a tag

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

Show stats for a tag

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

Delete a tag

$mailgun->tags()->delete('example.com', '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
    
    exit();
}

// The signature is valid

Show all webhooks

$mailgun->webhooks()->index('example.com');

Show a single webhooks

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

Create a webhooks

$mailgun->webhooks()->create('example.com', 'accept', 'https://www.exmple.com/webhook');

Update a webhooks

$mailgun->webhooks()->update('example.com', 4711, 'https://www.exmple.com/webhook');

Delete a webhooks

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