nmirceac/mailgun

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

维护者

详细信息

github.com/nmirceac/mailgun

主页

源代码

问题

安装次数: 10

依赖者: 1

建议者: 0

安全: 0

星标: 0

关注者: 2

分支: 0

开放问题: 0

dev-master 2021-05-22 17:49 UTC

Requires

Requires (Dev)

Suggests

MIT 2def3cb541bbd9f4ddec0307fbdcecbb354173fc

  • Chris Bogaards <chris.woop@bogardo.com>
  • Mircea Nicolae <nmirceac.woop@gmail.com>

mailemaillaravelmailgunbogardoattachDatarevival

This package is auto-updated.

Last update: 2024-09-26 09:51:52 UTC

README

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

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 键在 Service Container 中注册它。

注册 必须 在注册 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 邮件组件 大多数功能。

可以使用 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 数组。

注意：在电子邮件视图中始终会传递一个 $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 向每个收件人发送带有他们电子邮件地址的单独电子邮件，只出现在 to 字段中。如果不使用，所有收件人的电子邮件地址将显示在每个收件人的 to 字段中。

示例
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 配置设置，则将自动为所有消息设置 reply-to。您可以通过将其添加到消息中覆盖此值，如示例所示。

附件

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

attach 方法接受 2 个参数

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

内嵌图片

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

调度

Mailgun 提供了设置邮件投递时间的能力，最多可提前 3 天。为此，您可以使用 later 方法。由于队列的动态性，消息不可能恰好按时到达，但 Mailgun 会尽力做到。

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

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

要在一分钟内发送电子邮件，您可以这样做

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']);
});

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

活动

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

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。它将生成随机的字母和数字。例如，此 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）。有关更多信息，请参阅许可文件。