mailgun-php

Mailgun's Official SDK for PHP

1,093

314

1,093

View on GitHub

Top Related Projects

PHPMailer

20,995

The classic email sending library for PHP

swiftmailer

9,551

Comprehensive mailing tools for PHP

sendgrid-php

1,488

The Official Twilio SendGrid PHP API Library

Quick Overview

Mailgun-php is the official PHP SDK for the Mailgun email automation service. It provides a simple and efficient way to integrate Mailgun's email sending, receiving, and tracking capabilities into PHP applications. This library simplifies the process of interacting with Mailgun's API, allowing developers to easily manage email campaigns and transactional emails.

Pros

Easy integration with Mailgun's API
Comprehensive support for Mailgun features (sending, receiving, tracking, etc.)
Well-documented and actively maintained
PSR-7 compliant, allowing for easy integration with modern PHP frameworks

Cons

Requires a Mailgun account and API key
Limited to Mailgun's service (not a generic email library)
Learning curve for developers unfamiliar with Mailgun's concepts
Dependency on external service may impact application reliability

Code Examples

Sending a simple email:

use Mailgun\Mailgun;

$mg = Mailgun::create('your-api-key');
$mg->messages()->send('your-domain.com', [
    'from'    => 'sender@example.com',
    'to'      => 'recipient@example.com',
    'subject' => 'Hello',
    'text'    => 'Testing some Mailgun awesomeness!'
]);

Adding an attachment to an email:

use Mailgun\Mailgun;

$mg = Mailgun::create('your-api-key');
$mg->messages()->send('your-domain.com', [
    'from'    => 'sender@example.com',
    'to'      => 'recipient@example.com',
    'subject' => 'Hello',
    'text'    => 'Testing some Mailgun awesomeness!',
    'attachment' => [
        ['filePath' => '/path/to/file.jpg', 'filename' => 'photo.jpg']
    ]
]);

Retrieving events:

use Mailgun\Mailgun;

$mg = Mailgun::create('your-api-key');
$events = $mg->events()->get('your-domain.com', [
    'limit' => 25,
    'filter' => 'delivered'
]);

Getting Started

Install the library using Composer:

composer require mailgun/mailgun-php php-http/guzzle6-adapter

Create a Mailgun instance with your API key:

use Mailgun\Mailgun;

$mg = Mailgun::create('your-api-key');

Use the instance to interact with Mailgun's API, for example, to send an email:

$mg->messages()->send('your-domain.com', [
    'from'    => 'sender@example.com',
    'to'      => 'recipient@example.com',
    'subject' => 'Hello',
    'text'    => 'It's so simple to send a message!'
]);

Competitor Comparisons

mailer

1,484

Helps sending emails

Pros of symfony/mailer

Part of the Symfony ecosystem, integrating seamlessly with other Symfony components
Supports multiple email providers and can easily switch between them
Offers a more abstracted and flexible API for sending emails

Cons of symfony/mailer

Steeper learning curve for developers not familiar with Symfony
May have more overhead for simple email sending tasks
Less specialized for Mailgun-specific features compared to mailgun-php

Code Comparison

mailgun-php:

$mg = Mailgun::create('key-example');
$mg->messages()->send('example.com', [
  'from'    => 'bob@example.com',
  'to'      => 'alice@example.com',
  'subject' => 'Hello',
  'text'    => 'Testing some Mailgun awesomeness!'
]);

symfony/mailer:

$email = (new Email())
    ->from('bob@example.com')
    ->to('alice@example.com')
    ->subject('Hello')
    ->text('Testing some Symfony Mailer awesomeness!');
$mailer->send($email);

Both libraries provide straightforward ways to send emails, but symfony/mailer offers a more object-oriented approach with its Email class. mailgun-php is more focused on Mailgun-specific features, while symfony/mailer provides a more generic interface that can work with various email providers.

PHPMailer

20,995

The classic email sending library for PHP

Pros of PHPMailer

Standalone library with no external dependencies
Supports a wide range of email protocols (SMTP, mail(), sendmail)
Extensive documentation and large community support

Cons of PHPMailer

Requires more configuration and setup compared to Mailgun
Limited built-in features for advanced email tracking and analytics
May require additional server configuration for optimal performance

Code Comparison

PHPMailer:

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'smtp.example.com';
$mail->SMTPAuth = true;
$mail->Username = 'user@example.com';
$mail->Password = 'secret';
$mail->setFrom('from@example.com', 'Mailer');
$mail->addAddress('recipient@example.com');
$mail->Subject = 'Here is the subject';
$mail->Body    = 'This is the HTML message body <b>in bold!</b>';
$mail->send();

Mailgun:

$mg = Mailgun::create('your-api-key');
$mg->messages()->send('example.com', [
  'from'    => 'Excited User <mailgun@example.com>',
  'to'      => 'recipient@example.com',
  'subject' => 'Hello',
  'text'    => 'Testing some Mailgun awesomeness!'
]);

The code comparison shows that Mailgun requires less setup and configuration, while PHPMailer offers more granular control over email settings. PHPMailer's code is more verbose but provides direct access to SMTP settings, while Mailgun abstracts these details away, resulting in simpler code for basic email sending tasks.

swiftmailer

9,551

Comprehensive mailing tools for PHP

Pros of SwiftMailer

Platform-independent and does not require external dependencies
Supports a wide range of transport methods (SMTP, sendmail, etc.)
Extensive documentation and community support

Cons of SwiftMailer

No built-in support for advanced features like email tracking or analytics
Requires more setup and configuration compared to Mailgun-PHP
Less optimized for high-volume email sending

Code Comparison

SwiftMailer:

$transport = new Swift_SmtpTransport('smtp.example.org', 25);
$mailer = new Swift_Mailer($transport);
$message = (new Swift_Message('Subject'))
  ->setFrom(['john@doe.com' => 'John Doe'])
  ->setTo(['receiver@domain.org'])
  ->setBody('Here is the message itself');
$result = $mailer->send($message);

Mailgun-PHP:

$mg = Mailgun::create('your-api-key');
$mg->messages()->send('example.com', [
  'from'    => 'bob@example.com',
  'to'      => 'sally@example.com',
  'subject' => 'The PHP SDK is awesome!',
  'text'    => 'It is so simple to send a message.'
]);

SwiftMailer offers more flexibility in transport methods and is platform-independent, making it suitable for various environments. However, Mailgun-PHP provides a simpler API for sending emails and includes built-in support for Mailgun-specific features. SwiftMailer requires more setup but offers greater control over the email sending process, while Mailgun-PHP is more straightforward to use but is tied to the Mailgun service.

sendgrid-php

1,488

The Official Twilio SendGrid PHP API Library

Pros of sendgrid-php

More comprehensive documentation and examples
Supports a wider range of email-related features (e.g., marketing campaigns, email validation)
Active community and frequent updates

Cons of sendgrid-php

Steeper learning curve due to more complex API
Larger library size, which may impact performance in some cases

Code Comparison

sendgrid-php:

$email = new \SendGrid\Mail\Mail();
$email->setFrom("test@example.com", "Example User");
$email->setSubject("Sending with SendGrid is Fun");
$email->addTo("test@example.com", "Example User");
$email->addContent("text/plain", "and easy to do anywhere, even with PHP");

mailgun-php:

$mg = Mailgun::create('key-example');
$mg->messages()->send('example.com', [
  'from'    => 'bob@example.com',
  'to'      => 'sally@example.com',
  'subject' => 'The PHP SDK is awesome!',
  'text'    => 'It is so simple to send a message.'
]);

Both libraries offer straightforward ways to send emails, but sendgrid-php uses a more object-oriented approach, while mailgun-php opts for a simpler function-based method. SendGrid's library provides more granular control over email components, which can be beneficial for complex use cases but may require more setup for basic tasks.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Mailgun PHP client

This is the Mailgun PHP SDK. This SDK contains methods for easily interacting with the Mailgun API. Below are examples to get you started. For additional examples, please see our official documentation at http://documentation.mailgun.com

Installation

To install the SDK, you will need to be using Composer in your project. If you aren't using Composer yet, it's really simple! Here's how to install composer:

curl -sS https://getcomposer.org/installer | php

Required minimum php version

minimum php version 7.4

The Mailgun API Client is not hard coupled to Guzzle, Buzz or any other library that sends HTTP messages. Instead, it uses the PSR-18 client abstraction. This will give you the flexibility to choose what PSR-7 implementation and HTTP client you want to use.

If you just want to get started quickly you should run the following command:

composer require mailgun/mailgun-php symfony/http-client nyholm/psr7

Usage

You should always use Composer autoloader in your application to automatically load your dependencies. All the examples below assume you've already included this in your file:

require 'vendor/autoload.php';
use Mailgun\Mailgun;

Here's how to send a message using the SDK:

// First, instantiate the SDK with your API credentials
$mg = Mailgun::create('key-example'); // For US servers
$mg = Mailgun::create('key-example', 'https://api.eu.mailgun.net'); // For EU servers

// Now, compose and send your message.
// $mg->messages()->send($domain, $params);
$mg->messages()->send('example.com', [
  'from'    => 'bob@example.com',
  'to'      => 'sally@example.com',
  'subject' => 'The PHP SDK is awesome!',
  'text'    => 'It is so simple to send a message.'
]);

Attention: $domain must match to the domain you have configured on app.mailgun.com.

Usage of new method for updating web scheme

# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('KEY', 'FULL_DOMAIN_URL');
$domain = "DOMAIN";

# Issue the call to the client.
$result = $mgClient->domains()->updateWebScheme($domain, 'https');

print_r($result);

Update web prefix

# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('KEY', 'FULL_DOMAIN_URL');
$domain = "DOMAIN";

# Issue the call to the client.
$result = $mgClient->domains()->updateWebPrefix($domain, 'tracking');
print_r($result);

Example of response

Mailgun\Model\Domain\WebPrefixResponse Object
(
    [message:Mailgun\Model\Domain\AbstractDomainResponse:private] => Domain web prefix updated
    [domain:Mailgun\Model\Domain\AbstractDomainResponse:private] =>
    [inboundDnsRecords:Mailgun\Model\Domain\AbstractDomainResponse:private] => Array
        (
        )
    [outboundDnsRecords:Mailgun\Model\Domain\AbstractDomainResponse:private] => Array
        (
        )
)

Custom http request to the API

<?php
# Include the Autoloader (see "Libraries" for install instructions)
require 'vendor/autoload.php';
use Mailgun\Mailgun;

# Instantiate the client.
$mgClient = Mailgun::create('KEY', 'ENDPOINT');
$domain = "DOMAIN";

$path = 'some path';
$params = [];

# Issue the call to the client.
$resultPost = $mgClient->httpClient()->httpPost($path, $params);

$resultGet = $mgClient->httpClient()->httpGet($path, $params);

$resultPut = $mgClient->httpClient()->httpPut($path, $params);

$resultDelete = $mgClient->httpClient()->httpDelete($path, $params);

SubAccounts

//Enable Sub Account
try {
    $items = $mgClient->subaccounts()->enable($id);
} catch (Exception $exception) {
    echo sprintf('HTTP CODE - %s,', $exception->getCode());
    echo sprintf('Error - %s', $exception->getMessage());
}

//Create a new Sub Account
try {
    $items = $mgClient->subaccounts()->create('some name');
} catch (Exception $exception) {
    echo sprintf('HTTP CODE - %s,', $exception->getCode());
    echo sprintf('Error - %s', $exception->getMessage());
}

//Get All
try {
    $items = $mgClient->subaccounts()->index();

    print_r($items->getItems());
} catch (Exception $exception) {
    echo sprintf('HTTP CODE - %s,', $exception->getCode());
    echo sprintf('Error - %s', $exception->getMessage());
}

Performing API Requests "On Behalf Of" Subaccounts

More Detailed you can read here - https://help.mailgun.com/hc/en-us/articles/16380043681435-Subaccounts#01H2VMHAW8CN4A7WXM6ZFNSH4R

$mgClient = Mailgun::create(
    'xxx',
    'yyy',
    $subAccountId
);

use Mailgun\HttpClient\HttpClientConfigurator;
use Mailgun\Hydrator\NoopHydrator;

$configurator = new HttpClientConfigurator();
$configurator->setEndpoint('http://bin.mailgun.net/aecf68de');
$configurator->setApiKey('key-example');
$configurator->setSubAccountId($subAccountId)

All usage examples

You will find more detailed documentation at /doc and on https://documentation.mailgun.com.

Response

The result of an API call is, by default, a domain object. This will make it easy to understand the response without reading the documentation. One can just read the doc blocks on the response classes. This provides an excellent IDE integration.

$mg = Mailgun::create('key-example');
$dns = $mg->domains()->show('example.com')->getInboundDNSRecords();

foreach ($dns as $record) {
  echo $record->getType();
}

If you'd rather work with an array than an object you can inject the ArrayHydrator to the Mailgun class.

use Mailgun\Hydrator\ArrayHydrator;

$configurator = new HttpClientConfigurator();
$configurator->setApiKey('key-example');

$mg = new Mailgun($configurator, new ArrayHydrator());
$data = $mg->domains()->show('example.com');

foreach ($data['receiving_dns_records'] as $record) {
  echo isset($record['record_type']) ? $record['record_type'] : null;
}

You can also use the NoopHydrator to get a PSR7 Response returned from the API calls.

Warning: When using NoopHydrator there will be no exceptions on a non-200 response.

Debugging

Debugging the PHP SDK can be helpful when things aren't working quite right. To debug the SDK, here are some suggestions:

Set the endpoint to Mailgun's Postbin. A Postbin is a web service that allows you to post data, which then you can display it through a browser. Using Postbin is an easy way to quickly determine what data you're transmitting to Mailgun's API.

Step 1 - Create a new Postbin. Go to http://bin.mailgun.net. The Postbin will generate a special URL. Save that URL.

Step 2 - Instantiate the Mailgun client using Postbin.

Tip: The bin id will be the URL part after bin.mailgun.net. It will be random generated letters and numbers. For example, the bin id in this URL (http://bin.mailgun.net/aecf68de) is aecf68de.

use Mailgun\HttpClient\HttpClientConfigurator;
use Mailgun\Hydrator\NoopHydrator;

$configurator = new HttpClientConfigurator();
$configurator->setEndpoint('http://bin.mailgun.net/aecf68de');
$configurator->setApiKey('key-example');
$configurator->setDebug(true);

$mg = new Mailgun($configurator, new NoopHydrator());

# Now, compose and send your message.
$mg->messages()->send('example.com', [
  'from'    => 'bob@example.com',
  'to'      => 'sally@example.com',
  'subject' => 'The PHP SDK is awesome!',
  'text'    => 'It is so simple to send a message.'
]);

Additional Info

For usage examples on each API endpoint, head over to our official documentation pages.

This SDK includes a Message Builder, Batch Message.

Message Builder allows you to quickly create the array of parameters, required to send a message, by calling a methods for each parameter. Batch Message is an extension of Message Builder, and allows you to easily send a batch message job within a few seconds. The complexity of batch messaging is eliminated!

Framework integration

If you are using a framework you might consider these composer packages to make the framework integration easier.

tehplague/swiftmailer-mailgun-bundle for Symfony
katanyoo/yii2-mailgun-mailer for Yii2
narendravaghela/cakephp-mailgun for CakePHP
drupal/mailgun for Drupal
Laravel Mail comes with Mailgun driver support

Contribute

This SDK is an Open Source under the MIT license. It is, thus, maintained by collaborators and contributors.

Feel free to contribute in any way. As an example you may:

Trying out the dev-master code
Create issues if you find problems
Reply to other people's issues
Review PRs

Running the test code

If you want to run the tests you should run the following commands:

git clone git@github.com:mailgun/mailgun-php.git
cd mailgun-php
composer update
composer test

Support and Feedback

Be sure to visit the Mailgun official documentation website for additional information about our API.

If you find a bug, please submit the issue in Github directly. Mailgun-PHP Issues

As always, if you need additional assistance, drop us a note through your account at https://app.mailgun.com/support.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot