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:

• Attachments
• Pagination
• Message Builder
• Batch Message

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

Email Validation API

Validate a single address (v3)

Note: Email address validation v3 has been depreciated in favor of v4.

$mailgun->EmailValidation()->validate('alice@example.com');

Validate a single address (v4)

$mailgun->EmailValidationV4()->validate('alice@example.com');

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 (old version)

Below in an example how to create a Mime message with SwiftMailer (this one is outdated).

$message = new Swift_Message('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(), []);

Send a message with Mime (Recommended)

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

$email = (new \Symfony\Component\Mime\Email())
    ->from('mailgun@example.com')
    ->to('bestcustomer@example.com')
    ->cc('cc@example.com')
    ->bcc('bcc@example.com')
    ->replyTo('fabien@example.com')
    //->priority('some priority')
    ->subject('Time for Symfony Mailer!')
    ->text('Sending emails is fun again!')
    ->html('<p>Your awesome text!</p>');

$mailgun->messages()->sendMime($domain, $recipients, $email->getHtmlBody(), $params);

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](https://github.com/gmail).com')";
$actions = ["forward('alice@example.com')"];
$description = 'Test route';

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

Update a route

$expression = "match_recipient('.*[@gmail](https://github.com/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', 'opened', [ '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);