bogardo/mailgun

此包已被废弃，不再维护。未建议替代包。

Laravel 包，用于通过 Mailgun API 发送邮件

维护者

详细信息

github.com/Bogardo/Mailgun

主页

源代码

问题

安装量: 708 407

依赖者: 2

建议者: 0

安全性: 0

星标: 292

关注者: 23

分支: 92

开放问题: 27

5.2.0 2019-10-16 22:19 UTC

Requires

Requires (Dev)

Suggests

MIT 86aca9ffb07d46c1bcd7540d1f74abaf90803385

mailemaillaravelmailgunbogardo

This package is auto-updated.

Last update: 2020-04-16 23:20:34 UTC

README

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

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

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

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

此包使用了 mailgun-php 库。

Total Downloads Monthly Downloads License Gitter

基本示例
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 进行通信。要注册您的驱动程序，您必须使用 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 array。

注意：始终会将 $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 方法接受两个参数

  • $path | 图片的路径
  • $name | （可选）文件的 远程 名称（附件将在服务器端重命名）
$message->attach($path, $name);

内嵌图片

将内嵌图片嵌入到您的电子邮件中非常简单。在您的视图中，您可以使用 embed 方法并将文件的路径传递给它。这将返回一个 CID（内容标识符），它将用作图像的 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>

$message 变量总是通过 Mailgun 类传递到电子邮件视图中。

调度

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 方法。

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

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

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

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

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

活动

如果您想使电子邮件成为 Mailgun 中创建的活动的一部分，您可以使用 campaign 方法将活动添加到消息中。此方法接受单个 string ID 或 ID 的 array（最多 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将是bin.mailgun.net之后的URL部分。它将是随机生成的字母和数字。例如，此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。此地址成为此邮件列表的ID。

当您向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散列的工具。

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

注册

  1. 收件人请求订阅
  2. 使用OptInHandler生成OptIn链接
  3. 向收件人发送OptIn链接的电子邮件

验证

  1. 收件人点击OptIn链接
  2. 使用OptInHandler验证OptIn链接
  3. 订阅用户
示例
$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）。有关更多信息，请参阅许可文件。