PHPackages                             mailgun/mailgun-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. mailgun/mailgun-php

ActiveLibrary[Mail & Notifications](/categories/mail)

mailgun/mailgun-php
===================

The Mailgun SDK provides methods for all API functions.

v4.5.0(1mo ago)1.2k30.2M↓35.9%314[1 issues](https://github.com/mailgun/mailgun-php/issues)[1 PRs](https://github.com/mailgun/mailgun-php/pulls)20MITPHPPHP ^7.4 || ^8.0CI passing

Since Aug 16Pushed 1mo ago84 watchersCompare

[ Source](https://github.com/mailgun/mailgun-php)[ Packagist](https://packagist.org/packages/mailgun/mailgun-php)[ RSS](/packages/mailgun-mailgun-php/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (39)Versions (74)Used By (20)

Mailgun PHP SDK
===============

[](#mailgun-php-sdk)

The official Mailgun PHP SDK — a clean, PSR-18 HTTP client wrapper around the [Mailgun API](https://documentation.mailgun.com/docs/mailgun/api-reference).

[![Latest Version](https://camo.githubusercontent.com/4bbb98c8f62222263edbe1adf047e4d3d3d9c109377cf9530954b885b29647fe/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f6d61696c67756e2f6d61696c67756e2d7068702e7376673f7374796c653d666c61742d737175617265)](https://github.com/mailgun/mailgun-php/releases)[![Total Downloads](https://camo.githubusercontent.com/d299ae7f40bb42bbdc3ae4d455aa3194b307035d27127a56bb543dc5e2e63a85/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d61696c67756e2f6d61696c67756e2d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mailgun/mailgun-php)[![License](https://camo.githubusercontent.com/e94bd57b6e898c2dbbed9d36f83de51f83b5cbe91940a0ede9e0c5edcdfc5b3c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6d61696c67756e2f6d61696c67756e2d7068703f7374796c653d666c61742d737175617265)](LICENSE)[![Join the chat at https://gitter.im/mailgun/mailgun-php](https://camo.githubusercontent.com/ee316ab2784d4f36516e572fefa0af5db4795fddc97644865c2c7b82656174e2/68747470733a2f2f6261646765732e6769747465722e696d2f6d61696c67756e2f6d61696c67756e2d7068702e737667)](https://gitter.im/mailgun/mailgun-php?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

---

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Sending Email](#sending-email)
- [IP Management](#ip-management)
- [Dynamic IP Pools](#dynamic-ip-pools-dipp)
- [Analytics](#analytics)
- [Subaccounts](#subaccounts)
- [Response Handling](#response-handling)
- [Debugging](#debugging)
- [Framework Integration](#framework-integration)
- [Contributing](#contributing)

---

Requirements
------------

[](#requirements)

- PHP **7.4** or higher
- A PSR-18 HTTP client (e.g. `symfony/http-client`, `guzzlehttp/guzzle`)
- A PSR-7 / PSR-17 implementation (e.g. `nyholm/psr7`)

The SDK is not coupled to any specific HTTP library — bring your own PSR-18 client.

---

Installation
------------

[](#installation)

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

> **EU region?** Use `https://api.eu.mailgun.net` as your endpoint (see below).

---

Quick Start
-----------

[](#quick-start)

```
require 'vendor/autoload.php';

use Mailgun\Mailgun;

// US servers (default)
$mg = Mailgun::create('your-api-key');

// EU servers
$mg = Mailgun::create('your-api-key', 'https://api.eu.mailgun.net');
```

> **Note:** The `$domain` you pass to any API call must match a domain configured in [app.mailgun.com](https://app.mailgun.com/app/domains).

---

Sending Email
-------------

[](#sending-email)

### Simple message

[](#simple-message)

```
$mg->messages()->send('example.com', [
    'from'    => 'Alice ',
    'to'      => 'bob@example.com',
    'subject' => 'Hello from Mailgun!',
    'text'    => 'This is a plain-text body.',
    'html'    => 'This is an HTML body.',
]);
```

### With attachments and tracking options

[](#with-attachments-and-tracking-options)

```
$mg->messages()->send('example.com', [
    'from'       => 'alice@example.com',
    'to'         => ['bob@example.com', 'carol@example.com'],
    'subject'    => 'Monthly report',
    'text'       => 'Please find the report attached.',
    'attachment' => [['filePath' => '/tmp/report.pdf', 'filename' => 'report.pdf']],
    'o:tracking' => 'yes',
    'o:tag'      => ['monthly', 'report'],
]);
```

### Scheduled delivery

[](#scheduled-delivery)

```
$mg->messages()->send('example.com', [
    'from'           => 'alice@example.com',
    'to'             => 'bob@example.com',
    'subject'        => 'See you tomorrow',
    'text'           => 'Scheduled for tomorrow morning.',
    'o:deliverytime' => 'tomorrow 9am UTC',
]);
```

---

IP Management
-------------

[](#ip-management)

### List all account IPs

[](#list-all-account-ips)

```
$response = $mg->ips()->index();

foreach ($response->getItems() as $ip) {
    echo $ip . PHP_EOL;
}

// Dedicated only
$dedicated = $mg->ips()->index(dedicated: true);

// With full details (pool assignments, subaccount ownership, timestamps)
$detailed = $mg->ips()->listIpsDetailed([
    'pool_id'      => 'my-pool-id', // filter by pool ('any' or 'none' also accepted)
    'subaccount_id'=> 'sub-123',
    'limit'        => 25,
]);

foreach ($detailed->getItems() as $ip) {
    echo "{$ip['address']} — pools: " . implode(', ', $ip['pool_ids']) . PHP_EOL;
}
```

### Inspect a single IP

[](#inspect-a-single-ip)

```
$ip = $mg->ips()->show('1.2.3.4');

echo $ip->getIp();       // "1.2.3.4"
echo $ip->getRdns();     // reverse DNS
var_dump($ip->getDedicated()); // bool
```

### Assign / remove an IP on a specific domain

[](#assign--remove-an-ip-on-a-specific-domain)

```
// Add IP to a domain
$mg->ips()->assign('example.com', '1.2.3.4');

// Remove IP from a domain
$mg->ips()->unassign('example.com', '1.2.3.4');

// List IPs currently assigned to a domain
$response = $mg->ips()->domainIndex('example.com');
print_r($response->getItems());
```

### Bulk IP operations across all domains

[](#bulk-ip-operations-across-all-domains)

```
// Assign an IP to every domain in the account (async)
$ref = $mg->ips()->assignIpToAllDomains('1.2.3.4');
echo $ref->getReferenceId(); // track the async operation

// Remove an IP from all domains, replacing it with another
$ref = $mg->ips()->removeIpFromAllDomains('1.2.3.4', alternative: '5.6.7.8');
echo $ref->getMessage();
```

### Find all domains using a specific IP

[](#find-all-domains-using-a-specific-ip)

```
$response = $mg->ips()->domainsByIp('1.2.3.4', limit: 20, search: 'example');

foreach ($response->getItems() as $domain) {
    echo $domain . PHP_EOL;
}
```

### Dedicated IP band

[](#dedicated-ip-band)

```
// Move an account IP into a dedicated IP band
$mg->ips()->placeAccountIpToBand('1.2.3.4');
```

### Request a new dedicated IP

[](#request-a-new-dedicated-ip)

```
// Check how many dedicated IPs your plan allows
$available = $mg->ips()->numberOfIps();

// Provision a new dedicated IP
$mg->ips()->addDedicatedIp();
```

---

Dynamic IP Pools (DIPP)
-----------------------

[](#dynamic-ip-pools-dipp)

Dynamic IP Pools let you group dedicated IPs and link them to domains, so sending traffic is spread across all IPs in the pool automatically.

### List and inspect pools

[](#list-and-inspect-pools)

```
// All pools in the account
$response = $mg->ips()->listIpPools();

foreach ($response->getIpPools() as $pool) {
    echo "{$pool['pool_id']} — {$pool['name']}" . PHP_EOL;
    echo "  IPs: " . implode(', ', $pool['ips']) . PHP_EOL;
    echo "  Linked to domains: " . ($pool['is_linked'] ? 'yes' : 'no') . PHP_EOL;
}

// Single pool details
$pool = $mg->ips()->loadDIPPInformation('my-pool-id');

echo $pool->getPoolId();      // "my-pool-id"
echo $pool->getName();        // "Primary sending pool"
echo $pool->getDescription(); // "Main US sending pool"
print_r($pool->getIps());     // ["1.2.3.4", "5.6.7.8"]
var_dump($pool->isLinked());  // bool — whether domains are attached
```

### Create and configure a pool

[](#create-and-configure-a-pool)

```
// Create a new pool
$mg->ips()->createIpPool('Primary Pool', 'Main US outbound pool');

// Modify pool metadata, add/remove IPs, link/unlink domains — all in one call
$mg->ips()->updateIpPool('my-pool-id', [
    'name'          => 'Primary Pool v2',
    'add_ip'        => '9.10.11.12',
    'remove_ip'     => '1.2.3.4',
    'link_domain'   => 'example.com',
    'unlink_domain' => 'old.example.com',
]);
```

### Manage IPs inside a pool

[](#manage-ips-inside-a-pool)

```
// Add a single IP to a pool
$mg->ips()->addIpToPool('my-pool-id', '9.10.11.12');

// Add multiple IPs at once
$mg->ips()->addIpsToPool('my-pool-id', ['9.10.11.12', '13.14.15.16']);

// Remove an IP from a pool
$mg->ips()->removeIpFromPool('my-pool-id', '1.2.3.4');
```

> When a pool is linked to domains, adding or removing IPs propagates to all linked domains **asynchronously** after the API responds.

### List domains linked to a pool

[](#list-domains-linked-to-a-pool)

```
$response = $mg->ips()->getIpPoolDomains('my-pool-id', limit: 20);

foreach ($response->getDomains() as $domain) {
    echo $domain['name'] . PHP_EOL;
}

// Paginate using the cursor from the previous response
if ($response->getNextPage()) {
    $next = $mg->ips()->getIpPoolDomains('my-pool-id', page: $response->getNextPage());
}
```

### Delete a pool

[](#delete-a-pool)

```
// Delete without replacement (pool must not be linked to any domains)
$mg->ips()->deleteDIPP('my-pool-id');

// Replace linked domains with a specific IP before deleting
$mg->ips()->deleteDIPP('my-pool-id', replacementIp: '1.2.3.4');

// Replace linked domains with another pool before deleting
$mg->ips()->deleteDIPP('my-pool-id', replacementPoolId: 'backup-pool-id');
```

### Delegate a pool to a subaccount

[](#delegate-a-pool-to-a-subaccount)

```
// Grant a subaccount access to a pool
$mg->ips()->delegateIpPool('my-pool-id', 'sub-account-id');

// Revoke subaccount access
$mg->ips()->revokeDelegatedIpPool('my-pool-id', 'sub-account-id');
```

---

Analytics
---------

[](#analytics)

```
$result = $mg->metrics()->loadMetrics([
    'start'      => 'Sun, 22 Dec 2024 00:00:00 +0000',
    'end'        => 'Sun, 29 Dec 2024 00:00:00 +0000',
    'resolution' => 'day',
    'dimensions' => ['time'],
    'metrics'    => ['accepted_count', 'delivered_count', 'clicked_rate', 'opened_rate'],
    'include_aggregates'  => true,
    'include_subaccounts' => true,
]);

foreach ($result->getItems() as $item) {
    echo $item['dimensions']['time'] . ': ' . $item['metrics']['delivered_count'] . ' delivered' . PHP_EOL;
}
```

---

Subaccounts
-----------

[](#subaccounts)

```
// Create a subaccount
$mg->subaccounts()->create('Marketing Team');

// List all subaccounts
$items = $mg->subaccounts()->index();
print_r($items->getItems());

// Enable / disable
$mg->subaccounts()->enable($subAccountId);
$mg->subaccounts()->disable($subAccountId);
```

### Make API calls on behalf of a subaccount

[](#make-api-calls-on-behalf-of-a-subaccount)

```
// Pass the subaccount ID as the third argument to Mailgun::create()
$mg = Mailgun::create('your-api-key', 'https://api.mailgun.net', $subAccountId);

// All subsequent calls are scoped to that subaccount
$mg->messages()->send('example.com', [...]);
```

---

Response Handling
-----------------

[](#response-handling)

All API methods return typed model objects with IDE-friendly getters by default.

```
$domain = $mg->domains()->show('example.com');

foreach ($domain->getInboundDNSRecords() as $record) {
    echo $record->getType() . ': ' . $record->getValue() . PHP_EOL;
}
```

### Array responses

[](#array-responses)

Prefer raw arrays? Inject `ArrayHydrator`:

```
use Mailgun\Hydrator\ArrayHydrator;
use Mailgun\HttpClient\HttpClientConfigurator;

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

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

$data = $mg->domains()->show('example.com');
// $data is now a plain associative array
```

### Raw PSR-7 response

[](#raw-psr-7-response)

Need the raw response? Use `NoopHydrator` — **note: no exceptions are thrown on non-200 responses when using this hydrator.**

```
use Mailgun\Hydrator\NoopHydrator;

$mg = new Mailgun($configurator, new NoopHydrator());
$response = $mg->messages()->send('example.com', [...]);
// $response is a Psr\Http\Message\ResponseInterface
echo $response->getStatusCode();
```

---

Debugging
---------

[](#debugging)

Route traffic through Mailgun's [Postbin](http://bin.mailgun.net) to inspect what the SDK sends:

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

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

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

$mg->messages()->send('example.com', [
    'from'    => 'alice@example.com',
    'to'      => 'bob@example.com',
    'subject' => 'Debug test',
    'text'    => 'Checking what hits the wire.',
]);
```

### Custom HTTP requests

[](#custom-http-requests)

```
$client = $mg->httpClient();

$client->httpGet('/v3/domains', ['limit' => 5]);
$client->httpPost('/v3/some/path', ['key' => 'value']);
$client->httpPut('/v3/some/path', ['key' => 'value']);
$client->httpDelete('/v3/some/path');
```

---

Framework Integration
---------------------

[](#framework-integration)

FrameworkPackageSymfony[tehplague/swiftmailer-mailgun-bundle](https://github.com/tehplague/swiftmailer-mailgun-bundle)Yii2[katanyoo/yii2-mailgun-mailer](https://github.com/katanyoo/yii2-mailgun-mailer)CakePHP[narendravaghela/cakephp-mailgun](https://github.com/narendravaghela/cakephp-mailgun)Drupal[drupal/mailgun](https://www.drupal.org/project/mailgun)LaravelBuilt-in — see [Laravel Mail docs](https://laravel.com/docs/mail#mailgun-driver)---

Contributing
------------

[](#contributing)

This is an open-source project under the MIT license, maintained by Mailgun and the community.

### Running the tests

[](#running-the-tests)

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

### Ways to help

[](#ways-to-help)

- Test the `dev-master` branch and open issues for anything broken
- Review open pull requests
- Add tests for untested endpoints
- Improve documentation and examples

---

Support
-------

[](#support)

- **Documentation:** [documentation.mailgun.com](https://documentation.mailgun.com/docs/mailgun/api-reference)
- **Issues:** [GitHub Issues](https://github.com/mailgun/mailgun-php/issues)
- **Account support:** [app.mailgun.com/support](https://app.mailgun.com/support)
- **More examples:** [doc/examples.md](doc/examples.md)

###  Health Score

79

—

ExcellentBetter than 100% of packages

Maintenance91

Actively maintained with recent releases

Popularity75

Solid adoption and visibility

Community56

Growing community involvement

Maturity83

Battle-tested with a long release history

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~71 days

Recently: every ~97 days

Total

66

Last Release

41d ago

Major Versions

0.7 → 1.02013-08-20

v1.8 → v2.02016-04-02

2.8.1 → 3.0.0-beta12019-04-09

2.x-dev → 3.1.02020-10-08

v3.6.3 → v4.02023-12-16

PHP version history (5 changes)v2.0PHP ^5.5|^7.0

2.7.0PHP ^5.5 || ^7.0

3.0.0-beta1PHP ^7.1

3.3.0PHP ^7.3 || ^8.0

v4.3.0PHP ^7.4 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/401ccc5eea13c60cf807ae982af00e368e2166e2f26d8eb541dcd881a57385bc?d=identicon)[Nyholm](/maintainers/Nyholm)

![](https://www.gravatar.com/avatar/8cb2848c1835f91b936aef84d7bc6fdfed40d5c48fb6defa2804cbef6aeecc4f?d=identicon)[travelton](/maintainers/travelton)

![](https://www.gravatar.com/avatar/97e2c4b16b479b81d85e3adae1efc84d6c5d62ba8b0fd29e230bbf1750ef3b53?d=identicon)[mailgun](/maintainers/mailgun)

---

Top Contributors

[![Nyholm](https://avatars.githubusercontent.com/u/1275206?v=4)](https://github.com/Nyholm "Nyholm (209 commits)")[![oleksandr-mykhailenko](https://avatars.githubusercontent.com/u/9269550?v=4)](https://github.com/oleksandr-mykhailenko "oleksandr-mykhailenko (123 commits)")[![travelton](https://avatars.githubusercontent.com/u/241714?v=4)](https://github.com/travelton "travelton (76 commits)")[![DavidGarciaCat](https://avatars.githubusercontent.com/u/7809429?v=4)](https://github.com/DavidGarciaCat "DavidGarciaCat (66 commits)")[![pirogoeth](https://avatars.githubusercontent.com/u/472488?v=4)](https://github.com/pirogoeth "pirogoeth (12 commits)")[![Pavlico](https://avatars.githubusercontent.com/u/45973917?v=4)](https://github.com/Pavlico "Pavlico (10 commits)")[![obukhov-sergey](https://avatars.githubusercontent.com/u/617482?v=4)](https://github.com/obukhov-sergey "obukhov-sergey (9 commits)")[![z38](https://avatars.githubusercontent.com/u/3948085?v=4)](https://github.com/z38 "z38 (8 commits)")[![cerealean](https://avatars.githubusercontent.com/u/6100756?v=4)](https://github.com/cerealean "cerealean (8 commits)")[![aradoje](https://avatars.githubusercontent.com/u/30075502?v=4)](https://github.com/aradoje "aradoje (6 commits)")[![iwahara](https://avatars.githubusercontent.com/u/3982522?v=4)](https://github.com/iwahara "iwahara (6 commits)")[![mshcherb](https://avatars.githubusercontent.com/u/101879969?v=4)](https://github.com/mshcherb "mshcherb (6 commits)")[![yoye](https://avatars.githubusercontent.com/u/570307?v=4)](https://github.com/yoye "yoye (6 commits)")[![nathanntg](https://avatars.githubusercontent.com/u/194728?v=4)](https://github.com/nathanntg "nathanntg (5 commits)")[![qpautrat](https://avatars.githubusercontent.com/u/1844413?v=4)](https://github.com/qpautrat "qpautrat (5 commits)")[![svenbw](https://avatars.githubusercontent.com/u/837206?v=4)](https://github.com/svenbw "svenbw (5 commits)")[![ZebulanStanphill](https://avatars.githubusercontent.com/u/19592990?v=4)](https://github.com/ZebulanStanphill "ZebulanStanphill (4 commits)")[![Littlesqx](https://avatars.githubusercontent.com/u/16516151?v=4)](https://github.com/Littlesqx "Littlesqx (4 commits)")[![finwe](https://avatars.githubusercontent.com/u/195675?v=4)](https://github.com/finwe "finwe (4 commits)")[![indapublic](https://avatars.githubusercontent.com/u/856260?v=4)](https://github.com/indapublic "indapublic (4 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mailgun-mailgun-php/health.svg)

```
[![Health](https://phpackages.com/badges/mailgun-mailgun-php/health.svg)](https://phpackages.com/packages/mailgun-mailgun-php)
```

###  Alternatives

[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k26.1M293](/packages/openai-php-client)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.8M710](/packages/sylius-sylius)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.7k371.6k5](/packages/theodo-group-llphant)[deeplcom/deepl-php

Official DeepL API Client Library

2627.0M97](/packages/deeplcom-deepl-php)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28146.3k](/packages/phpro-http-tools)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)