README

这是一个用于通过Mailgun API发送邮件的Laravel框架插件。发送邮件的语法与Laravel Mail组件非常相似。

Laravel已经支持通过Mailgun API发送邮件，但是不支持Mailgun特定的功能。

此插件填补了这一空白，支持了Mailgun提供的多数邮件功能

打开与点击跟踪
活动
标签
定时投递
批量发送
自定义数据/头部信息

此插件使用了mailgun-php库。

基本示例

Mailgun::send('emails.invoice', $data, function ($message) {
    $message
        ->subject('Your Invoice')
        ->to('john.doe@example.com', 'John Doe')
        ->bcc('sales@company.com')
        ->attach(storage_path('invoices/12345.pdf'))
        ->trackClicks(true)
        ->trackOpens(true)
        ->tag(['tag1', 'tag2'])
        ->campaign(2);
});

版本兼容性

此插件目前支持Laravel 5.1及更高版本。对于旧版本的Laravel，请参阅此插件的旧版本。

安装

通过composer安装此插件

composer require bogardo/mailgun

如果使用Laravel 5.1到5.4，请注册ServiceProvider和（可选）Facade

// config/app.php

'providers' => [
    ...
    Bogardo\Mailgun\MailgunServiceProvider::class

];

...

'aliases' => [
	...
    'Mailgun' => Bogardo\Mailgun\Facades\Mailgun::class
],

然后，使用以下artisan命令发布配置文件。

php artisan vendor:publish --provider="Bogardo\Mailgun\MailgunServiceProvider" --tag="config"

或者如果使用Laravel 5.5

php artisan vendor:publish

发布后，将以下值添加到您的.env文件

# Domain name registered with Mailgun
MAILGUN_DOMAIN=

# Mailgun (private) API key
MAILGUN_PRIVATE=

# Mailgun public API key
MAILGUN_PUBLIC=

# You may wish for all e-mails sent with Mailgun to be sent from
# the same address. Here, you may specify a name and address that is
# used globally for all e-mails that are sent by this application through Mailgun.
MAILGUN_FROM_ADDRESS=
MAILGUN_FROM_NAME=

# Global reply-to e-mail address
MAILGUN_REPLY_TO=

# Force the from address
#
# When your `from` e-mail address is not from the domain specified some
# e-mail clients (Outlook) tend to display the from address incorrectly
# By enabling this setting, Mailgun will force the `from` address so the
# from address will be displayed correctly in all e-mail clients.
#
# WARNING:
# This parameter is not documented in the Mailgun documentation
# because if enabled, Mailgun is not able to handle soft bounces
MAILGUN_FORCE_FROM_ADDRESS=

# Testing
# 
# Catch All address
#
# Specify an email address that receives all emails send with Mailgun
# This email address will overwrite all email addresses within messages
MAILGUN_CATCH_ALL=

# Testing
# 
# Mailgun's testmode
#
# Send messages in test mode by setting this setting to true.
# When you do this, Mailgun will accept the message but will
# not send it. This is useful for testing purposes.
#
# Note: Mailgun DOES charge your account for messages sent in test mode.
MAILGUN_TESTMODE=

您还可以在您的config/mailgun.php中配置此插件。

HTTP客户端依赖

要删除特定HTTP客户端库（例如Guzzle）的依赖，mailgun-php库依赖于虚拟包php-http/client-implementation，允许您安装任何支持的客户端适配器，它不关心您选择哪一个。请参阅文档获取更多信息。

这给了您使用任何（支持的）客户端与Mailgun API通信的自由。要注册您的驱动，您必须在Service Container中使用mailgun.client键注册它。

注册必须在使用MailgunServiceProvider之前进行。

Guzzle 6示例实现

安装依赖

$ composer require php-http/guzzle6-adapter

将以下内容添加到您的AppServiceProvider的register()方法。

$this->app->bind('mailgun.client', function() {
	return \Http\Adapter\Guzzle6\Client::createWithConfig([
		// your Guzzle6 configuration
	]);
});

使用

Mailgun插件提供了与Laravel Mail组件类似的大部分功能。

可以使用Mailgun::send()方法发送电子邮件消息

Mailgun::send('emails.welcome', $data, function ($message) {
    $message->to('foo@example.com', 'John Doe')->subject('Welcome!');
});

视图

传递给send方法的第一个参数是要用作电子邮件正文的视图的名称。Mailgun支持两种正文类型：text和html。您可以如下指定正文类型

Mailgun::send(['html' => 'emails.htmlmail', 'text' => 'emails.textmail'], $data, $callback);

如果您同时有html正文和text正文，则无需指定类型，只需传递一个数组，其中第一个元素是html视图，第二个元素是text视图。

Mailgun::send(['emails.htmlmail','emails.textmail'], $data, $callback);

当您只想发送html正文时，只需传递一个string。

Mailgun::send(['emails.htmlmail'], $data, $callback);

当只发送text正文时，只需传递一个数组并指定类型。

Mailgun::send(['text' => 'emails.textmail'], $data, $callback);

原始

如果您不想使用模板，可以使用raw()方法。

Mailgun::raw("This is the email body", $callback);

数据

传递给send方法的第二个参数是传递给视图的$data 数组。

注意：一个$message变量始终传递给电子邮件视图，并允许在邮件正文中嵌入附件。因此，最好避免在视图有效负载中传递一个（自定义）message变量。

您可以使用数组键作为变量访问$data数组中的值。

示例

$data = [
	'customer' => 'John Doe',
	'url' => 'https://laravel.net.cn'
];

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->to('foo@example.com', 'John Doe')->subject('Welcome!');
});

视图emails.welcome

<body>
    Hi {{ $customer }},
	Please visit {{ $url }}
</body>

这将渲染

<body>
    Hi John Doe,
	Please visit https://laravel.net.cn
</body>

邮件选项

您可以在闭包中指定邮件选项。

收件人

to方法

Mailgun::send('emails.welcome', $data, function($message) {
	$message->to('foo@example.com', 'Recipient Name');
});

cc方法

$message->cc('foo@example.com', 'Recipient Name');

bcc方法

$message->bcc('foo@example.com', 'Recipient Name');

批量发送

Mailgun支持通过单个API调用向一组收件人发送邮件的能力。这是通过指定多个收件人电子邮件地址作为参数，并使用收件人变量来实现的。

收件人变量是您定义的自定义变量，您可以在消息正文中引用这些变量。它们允许您在单个API调用中使用自定义消息发送给每个收件人。

要访问电子邮件中的收件人变量，只需引用%recipient.yourkey%。

警告：在批量发送时，使用收件人变量也很重要。这将告诉Mailgun向每个收件人发送包含其电子邮件地址的单独电子邮件。如果不使用，每个收件人的电子邮件地址将显示在每个收件人的“收件人”字段中。

示例

use Bogardo\Mailgun\Mail\Message;

Mailgun::send('email.batch', $data, function(Message $message){
    $message->to([
        'user1@example.com' => [
            'name' => 'User One',
            'age' => 37,
            'city' => 'New York'
        ],
        'user2@example.com' => [
            'name' => 'User Two',
            'age' => 41,
            'city' => 'London'
        ]
    ]);
});

// Or

Mailgun::send('email.batch', $data, function(Message $message){
    $message->to('user1@example.com', 'User One', [
        'age' => 37, 
        'city' => 'New York'
    ]);
    $message->to('user2@example.com', 'User Two', [
        'age' => 41,
        'city' => 'London'
    ]);
});

// resources/views/email/batch.blade.php

Hi %recipient.name%,

Age: %recipient.age%
City: %recipient.city%

注意：Mailgun将每条消息的收件人数量限制为1000。

发件人

在Mailgun配置文件中，您已指定了from地址。如果您愿意，可以使用from方法来覆盖它。它接受两个参数：email和name，其中name字段是可选的。

// with name
$message->from('foo@example.com', 'Recipient Name');

// without name
$message->from('foo@example.com');

主题

设置电子邮件主题

$message->subject('Email subject');

回复到

设置回复地址

$message->replyTo('reply@example.com', 'Helpdesk');

如果已设置reply_to配置设置，则将自动为所有消息设置回复地址。您可以通过将其添加到消息中（如示例所示）来覆盖此值。

附件

要向电子邮件添加附件，可以使用attach方法。您可以添加多个附件。

attach方法接受2个参数

$path | 图像的路径
$name | （可选）文件的远程名称（附件将在服务器端重命名）

$message->attach($path, $name);

嵌入内联图像

将内联图像嵌入到电子邮件中非常简单。在您的视图中，您可以使用embed方法并传递文件的路径。这将返回一个CID（内容ID），它将用作图像的source。您可以在消息中添加多个内联图像。

embed方法接受2个参数

$path | 图像的路径
$name | （可选）文件的远程名称（附件将在服务器端重命名）

<body>
    <img src="{{ $message->embed($path, 'rename.png'); }}">
</body>

示例

输入

$data = [
	'img' => 'assets/img/example.png',
	'otherImg' => 'assets/img/foobar.jpg'
];

Mailgun::send('emails.welcome', $data, function ($message) {
I	$message->to('foo@example.com', 'Recipient Name');
});

<body>
    <img src="{{ $message->embed($img) }}">
    <img src="{{ $message->embed($otherImg, 'custom_name.jpg') }}">
</body>

输出

<body>
    <img src="cid:example.png">
    <img src="cid:custom_name.jpg">
</body>

Mailgun类始终通过邮件视图传递$message变量。

调度

Mailgun提供了设置电子邮件发送时间的能力，最多可达未来3天。为此，您可以使用later方法。由于队列的动态性质，消息不会保证在请求的时间恰好到达，但Mailgun会尽力做到。

later方法与（默认）send方法的工作方式相同，但它接受一个额外的参数。该额外参数是现在应发送消息的秒数（分钟、小时或天）。

如果指定时间超过3天限制，它将交付时间设置为3天的最大值。

要现在起60秒内发送电子邮件，您可以执行以下操作

Mailgun::later(60, 'emails.welcome', $data, function ($message) {
    $message->to('foo@example.com', 'John Doe')->subject('Welcome!');
});

当传递字符串或整数作为第一个参数时，它将将其解释为秒。您也可以通过传递一个键是类型而值是数量的数组来指定分钟、小时或天。例如，现在起5小时后发送

Mailgun::later(['hours' => 5], 'emails.welcome', $data, function($message) {
    $message->to('foo@example.com', 'John Doe')->subject('Welcome!');
});

您也可以传递一个DateTime或Carbon日期对象。

有时根据某些标准对发出的电子邮件流量进行分类是有帮助的，例如用于单独的注册电子邮件、密码恢复电子邮件或用户评论。Mailgun允许您使用自定义标签标记每条发出的消息。当您访问Mailgun控制面板内的报告页面时，可以按这些标签进行筛选。

警告：单条消息最多可标记3个标签。最大标签名称长度为128个字符。

Mailgun允许您拥有有限的标签数量。您总共可以有4000个唯一的标签。

要向您的电子邮件添加标签，您可以使用tag方法。

您可以通过提供一个字符串来向电子邮件添加单个标签。

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->tag('myTag');
});

要向电子邮件添加多个标签，您可以传递一个标签的数组。（最多3个）

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->tag(['Tag1', 'Tag2', 'Tag3']);
});

如果您向tag方法传递超过3个标签，它将仅使用前3个，其余的将被忽略。

活动

如果您希望您的电子邮件成为Mailgun中创建的活动的部分，您可以使用campaign方法将活动添加到消息中。此方法接受单个字符串 ID或ID的数组（最多3个）

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->campaign('my_campaign_id');
	//or
	$message->campaign(['campaign_1', 'campaign_2', 'campaign_3']);
});

跟踪点击

根据每条消息切换点击跟踪。比域级别设置具有更高的优先级。

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->trackClicks(true);
	//or
	$message->trackClicks(false);
});

跟踪打开

根据每条消息切换打开跟踪。比域级别设置具有更高的优先级。

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->trackOpens(true);
	//or
	$message->trackOpens(false);
});

DKIM

根据每条消息启用/禁用DKIM签名。（见Mailgun 文档）

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->dkim(true);
	// or
	$message->dkim(false);
});

测试模式

您可以在测试模式下发送消息。当您这样做时，Mailgun将接受消息但不会发送。这对于测试目的很有用。

注意：您将按测试模式发送的消息付费。

要为所有电子邮件启用测试模式，请将配置文件中的testmode选项设置为true。

要按消息切换启用/禁用测试模式

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->testmode(true);
	// or
	$message->testmode(false);
});

替代

将端点设置为Mailgun的Postbin。Postbin是一个允许您发布数据的网络服务，然后通过浏览器显示。这允许您快速确定实际发送到Mailgun API的内容。

步骤1 - 创建一个新的Postbin。

转到http://bin.mailgun.net。Postbin将生成一个特殊的URL。保存该URL。

步骤2 - 配置Mailgun客户端以使用Postbin。

提示：bin id将是URL部分，位于bin.mailgun.net之后。它将是随机生成的字母和数字。例如，此URL中的bin id，http://bin.mailgun.net/aecf68de，是"aecf68de"。

在您的config/mailgun.php中，更改以下内容

'api' => [
    'endpoint' => 'api.mailgun.net',
    'version' => 'v3',
    'ssl' => true
],

到

'api' => [
    'endpoint' => 'bin.mailgun.net',
    'version' => 'abc1de23', // your Bin ID
    'ssl' => false
],

现在，所有请求都将被发布到指定的Postbin，您可以在其中查看其内容。

头部

向您的消息添加自定义头部

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->header($name, $value);
});

数据

向您的消息添加自定义数据

Mailgun::send('emails.welcome', $data, function ($message) {
	$message->data($key, $value);
});

依赖注入

本文档中的所有示例都使用Mailgun外观。Mailgun服务已在容器中注册为mailgun，但您也可以使用接口Bogardo\Mailgun\Contracts\Mailgun在您的应用程序中进行依赖注入。

示例

namespace App\Http\Controllers;

class CustomController extends Controller
{

    /**
     * @var \Bogardo\Mailgun\Contracts\Mailgun
     */
    protected $mailgun;

    /**
     * @param \Bogardo\Mailgun\Contracts\Mailgun $mailgun
     */
    public function __construct(\Bogardo\Mailgun\Contracts\Mailgun $mailgun)
    {
        $this->mailgun = $mailgun;
    }
    
    public function index()
    {
        $this->mailgun->send($view, $data, $callback);
    }
}

邮件列表

您可以使用 Mailgun 邮件列表 API 编程创建邮件列表。邮件列表是一组成员（收件人），它本身具有一个电子邮件地址，例如 developers@example.com。此地址成为该邮件列表的标识符。

当您向 developers@example.com 发送消息时，列表中的所有成员都将收到其副本。

此包不包括对邮件列表 API 的完整支持。尽管如此，您可以使用此包与 API 通信，这应该会为您提供所需的所有灵活性。

一些示例

要全面了解所有可用的端点和接受的参数
请查阅官方 API 文档

获取所有列表（分页）

Mailgun::api()->get("lists/pages");

通过地址获取列表

Mailgun::api()->get("lists/{$list}");

创建新的列表

Mailgun::api()->post("lists", [
    'address'      => 'developers@example.com',
    'name'         => 'Developers',
    'description'  => 'Developers Mailing List',
    'access_level' => 'readonly'
]);

更新列表中的成员

Mailgun::api()->put("lists/{$list}/members/{$member}", [
    'address'      => 'new-email@example.com',
    'name'         => 'John Doe',
    'vars'         => json_encode(['age' => 35, 'country' => 'US']),
    'subscribed'   => 'no'
]);

再次，要全面了解所有可用的端点和接受的参数
请查阅官方 API 文档

OptInHandler

用于生成和验证 OptIn 哈希的实用工具。

使用此实用工具的典型流程如下

注册

收件人请求订阅
生成 OptIn 链接（使用 OptInHandler）
向收件人发送 OptIn 链接电子邮件

验证

收件人点击 OptIn 链接
验证 OptIn 链接（使用 OptInHandler）
订阅用户

示例

$secretKey   = 'a_very_secret_key';

注册

$listaddress = 'mailinglist@example.com';
$subscriber  = 'recipient@example.com';

$hash = Mailgun::optInHandler()->generateHash($listaddress, $secretKey, $subscriber);

var_dump($hash);
string 'eyJoIjoiODI2YWQ0OTRhNzkxMmZkYzI0MGJjYjM2MjFjMzAyY2M2YWQxZTY5MyIsInAiOiJleUp5SWpvaWNtVmphWEJwWlc1MFFHVjRZVzF3YkdVdVkyOXRJaXdpYkNJNkltMWhhV3hwYm1kc2FYTjBRR1Y0WVcxd2JHVXVZMjl0SW4wPSJ9' (length=180)

验证

$result = Mailgun::optInHandler()->validateHash($secretKey, $hash);

var_dump($result);
array (size=2)
	'recipientAddress' => string 'recipient@example.com' (length=21)
	'mailingList' => string 'mailinglist@example.com' (length=23)
  
// Subscribe the user to the mailinglist
Mailgun::api()->post("lists/{$result['mailingList']}/members", [
    'address' => $result['recipientAddress'],
    'subscribed' => 'yes'
]);

电子邮件验证

Mailgun 提供电子邮件验证服务，该服务检查以下内容

语法检查（RFC 定义语法）
DNS 验证
拼写检查
电子邮件服务提供商（ESP）特定的本地部分语法（如果可用）。

单个地址

验证单个地址

Mailgun::validator()->validate("foo@bar.com");

该 validate 方法返回以下对象

stdClass Object
(
    [address] => foo@bar.com
    [did_you_mean] => 
    [is_valid] => 1
    [parts] => stdClass Object
        (
            [display_name] => 
            [domain] => bar.com
            [local_part] => foo
        )

)

它还将尝试纠正拼写错误

Mailgun::validator()->validate("foo@gmil.com")

stdClass Object
(
    [address] => foo@gmil.com
    [did_you_mean] => foo@gmail.com
    [is_valid] => 1
    [parts] => stdClass Object
        (
            [display_name] => 
            [domain] => gmil.com
            [local_part] => foo
        )

)

多个地址

要验证多个地址，您可以使用 parse 方法。

此方法将分隔符分隔的电子邮件地址列表解析为两个列表：解析的地址和不可解析的部分。解析的地址是语法有效（并且可选地具有 DNS 和 ESP 特定语法检查）的地址列表；不可解析的列表是解析器无法理解的字符序列列表。这些通常与无效的电子邮件地址相匹配，但并不总是如此。分隔符字符是逗号（,）和分号（;）。

parse 方法接受两个参数

addresses: 地址数组或地址的分隔符分隔字符串
syntaxOnly: 仅执行语法检查或 DNS 和 ESP 特定验证。默认为 true

仅语法验证

$addresses = 'Alice <alice@example.com>,bob@example.com,example.com';
//or
$addresses = [
	'Alice <alice@example.com>',
	'bob@example.com',
	'example.com'
];

Mailgun::validator()->parse($addresses);

stdClass Object
(
    [parsed] => Array
        (
            [0] => Alice <alice@example.com>
            [1] => bob@example.com
        )

    [unparseable] => Array
        (
            [0] => example.com
        )

)

包含 DNS 和 ESP 验证的验证

$addresses = 'Alice <alice@example.com>,bob@example.com,example.com';
Mailgun::validator()->parse($addresses, false);

stdClass Object
(
    [parsed] => Array
        (
        )

    [unparseable] => Array
        (
            [0] => Alice <alice@example.com>
            [1] => bob@example.com
            [2] => example.com
        )

)

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件

ritey / mailgun

维护者

详细信息