daanra/mailgun

Laravel 邮件发送包，通过 Mailgun API 发送邮件，支持 Laravel 7

维护者

详细信息

github.com/Daanra/Mailgun

主页

源代码

安装次数: 8,837

依赖者: 0

建议者: 0

安全性: 0

星标: 2

关注者: 2

分支: 116

5.3.0 2020-06-02 18:35 UTC

Requires

Requires (Dev)

Suggests

MIT 4a9553a05a4e9cd0493185e350fc2bbe798737fa

mailemaillaravelmailgunbogardo

This package is auto-updated.

Last update: 2024-09-24 20:00:37 UTC

README

这是一个 Laravel 框架的包，用于使用 Mailgun API 发送邮件，支持 Laravel 7。最初从 此处 分支出来的。发送邮件的语法与 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 daanra/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 支持 2 种类型的正文：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调用向一组收件人发送邮件的能力。这是通过指定多个收件人电子邮件地址作为to参数并使用收件人变量来实现的。

收件人变量是您定义的自定义变量，您可以在消息正文中引用这些变量。它们使您能够在使用单个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类始终通过$消息变量将$消息变量传递给电子邮件视图。

调度

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将是 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. 生成 OptIn 链接（使用 OptInHandler）
  3. 通过电子邮件发送 OptIn 链接给收件人

验证

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