Mailgun PHP SDK

Mailgun PHP SDK is the official client for Mailgun’s transactional email API, wrapping message sending, domain and IP management, mailing lists, suppressions, templates, webhooks, and analytics behind a PSR-18/PSR-7 HTTP client interface. It ships model classes for each API resource (Model/Message, Model/Domain, Model/Templates, Model/Event, etc.) so responses come back as typed objects instead of raw arrays, and it’s HTTP-client-agnostic — bring any PSR-18 implementation such as Guzzle or Symfony’s HTTP client.

The library is a common integration point for PHP applications and frameworks (Laravel, Symfony) that need transactional or bulk email delivery, event tracking, and suppression-list management through Mailgun.

What You Get

• A single Mailgun client factory (Mailgun::create()) exposing sub-APIs for messages, domains, IPs, mailing lists, suppressions, templates, and webhooks
• Typed model classes under src/Model/* for every API resource instead of raw array responses
• Multipart message building for attachments via php-http/multipart-stream-builder
• HTTP-client-agnostic design via PSR-18/PSR-17, with HttpClient/Plugin for auth and error-handling middleware
• Dedicated exception classes under src/Exception for granular error handling

Common Use Cases

• Sending transactional emails (password resets, receipts, notifications) from a PHP backend or Laravel/Symfony app
• Managing sending domains, DNS, and dedicated IP pools programmatically
• Building and sending to mailing lists for newsletters or bulk campaigns
• Tracking bounces, complaints, and unsubscribes via the suppression and webhook APIs
• Validating email addresses at signup using the email validation API

Under The Hood

Architecture - The SDK centers on a Mailgun client class that composes per-resource API classes (Api/Message, Api/Domain, Api/MailingList, Api/Suppression, etc.), each returning typed model objects built via src/Hydrator; HTTP transport goes through HttpClient/Plugin-based middleware layered on any PSR-18 client, decoupling the SDK from a specific HTTP implementation. Tech Stack - PHP 7.4+/8.x built on the php-http HTTP Client Utilities ecosystem (client-common, discovery, multipart-stream-builder) plus PSR-7/PSR-18 interfaces, with webmozart/assert for input validation and dev-time PHPUnit/Psalm/PHP_CodeSniffer tooling. Code Quality - 99 test files back the client, and the repo enforces phpcompatibility, psalm, and PHPCS checks alongside ergebnis/composer-normalize, reflecting an actively maintained SDK with regular releases (latest v4.5.1). API Design - The resource-scoped API classes ($mg->messages(), $mg->domains(), $mg->mailingList()) mirror Mailgun’s REST resource structure closely, so the learning curve is low for anyone familiar with Mailgun’s HTTP API docs, and typed model responses reduce guesswork versus raw JSON; the tradeoff is that consumers must bring and configure their own PSR-18 client rather than getting one bundled.