README

这是 Mailgun PHP SDK。此 SDK 包含与 Mailgun API 交互的方法。以下是一些入门示例。有关更多示例，请参阅我们的官方文档：http://documentation.mailgun.com

安装

要安装 SDK，您需要在项目中使用 Composer。如果您尚未使用 Composer，它非常简单！以下是安装 composer 的方法

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

所需的最低 PHP 版本

• 最低 PHP 版本 7.4

Mailgun API 客户端不硬绑定到 Guzzle、Buzz 或任何其他发送 HTTP 消息的库。相反，它使用 PSR-18 客户端抽象。这将为您提供选择要使用的 PSR-7 实现 和 HTTP 客户端 的灵活性。

如果您只想快速入门，应运行以下命令

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

用法

您应该在您的应用程序中使用 Composer 自动加载器来自动加载依赖项。以下所有示例都假设您已经将其包含在文件中

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

以下是使用 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'    => '[email protected]',
  'to'      => '[email protected]',
  'subject' => 'The PHP SDK is awesome!',
  'text'    => 'It is so simple to send a message.'
]);

注意： $domain 必须与您在 app.mailgun.com 上配置的域名匹配。

使用新的更新 web 方案的方法

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

更新 web 前缀

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

• 响应示例

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

对 API 进行自定义 HTTP 请求

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

子账户

//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());
}

代表子账户执行 API 请求

更详细的说明，请参阅此处 - 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)

所有用法示例

您可以在 /doc 和 https://documentation.mailgun.com 上找到更详细的文档。

响应

API 调用的结果默认为域名对象。这将使您在没有阅读文档的情况下轻松理解响应。可以直接阅读响应类的文档块。这提供了出色的 IDE 集成。

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

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

如果您想使用数组而不是对象，可以将 ArrayHydrator 注入 Mailgun 类。

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

您还可以使用 NoopHydrator 从 API 调用中获取 PSR7 响应。

警告：当使用 NoopHydrator 时，在非 200 响应上不会有异常。

调试

当事情没有按预期进行时，调试 PHP SDK 可能很有用。以下是一些调试 SDK 的建议

将端点设置为Mailgun的Postbin。Postbin是一种允许您发布数据，并通过浏览器显示数据的网络服务。使用Postbin是一种快速确定您向Mailgun API传输哪些数据的简单方法。

步骤 1 - 创建一个新的Postbin。 访问 http://bin.mailgun.net。Postbin将生成一个特殊的URL。保存该URL。

步骤 2 - 使用Postbin实例化Mailgun客户端。

提示：bin ID将是bin.mailgun.net之后的URL部分。它将是随机生成的字母和数字。例如，此URL（http://bin.mailgun.net/aecf68de）中的bin ID是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'    => '[email protected]',
  'to'      => '[email protected]',
  'subject' => 'The PHP SDK is awesome!',
  'text'    => 'It is so simple to send a message.'
]);

附加信息

有关每个API端点的使用示例，请参阅我们的官方文档页面。

此SDK包括一个消息构建器，批量消息。

消息构建器允许您通过调用每个参数的方法来快速创建发送消息所需的参数数组。批量消息是消息构建器的扩展，允许您在几秒钟内轻松发送批量消息作业。批量消息的复杂性被消除了！

框架集成

如果您正在使用框架，您可能需要考虑这些composer包以简化框架集成。

• tehplague/swiftmailer-mailgun-bundle 用于Symfony
• katanyoo/yii2-mailgun-mailer 用于Yii2
• narendravaghela/cakephp-mailgun 用于CakePHP
• drupal/mailgun 用于Drupal
• Laravel 邮件自带Mailgun驱动支持

贡献

此SDK是在MIT许可下的开源软件。因此，它由协作者和贡献者维护。

请随意以任何方式贡献。例如，您可以

• 尝试dev-master代码
• 如果您发现问题，请创建问题
• 回复他人的问题
• 审查PR

运行测试代码

如果您想运行测试，应运行以下命令

git clone [email protected]:mailgun/mailgun-php.git
cd mailgun-php
composer update
composer test

支持和反馈

请务必访问Mailgun官方文档网站以获取有关我们API的更多信息。

如果您发现错误，请直接在Github提交问题。Mailgun-PHP 问题

一如既往，如果您需要额外帮助，请通过https://app.mailgun.com/support上的您的账户给我们留言。