bahricanli/mailgun

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

维护者

详情

github.com/bahricanli/Mailgun

主页

源代码

安装: 9

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 116

dev-master 2023-09-05 08:18 UTC

Requires

Requires (Dev)

Suggests

MIT 36223653d6a97b1f884312b6ca14c6a7af3e827e

mailemaillaravelmailgunbogardo

This package is not auto-updated.

Last update: 2024-09-17 16:34:39 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' => [
    ...
    BahriCanli\Mailgun\MailgunServiceProvider::class

];

...

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

接下来，使用以下 artisan 命令发布配置文件。

php artisan vendor:publish --provider="BahriCanli\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 支持 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 向每个收件人发送单独的电子邮件，其中只包含他们的电子邮件地址。如果不使用这些变量，每个收件人的电子邮件地址将显示在每个收件人的 to 字段中。

示例
use BahriCanli\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（内容-ID），它将用作图像的 source。您可以在消息中添加多个内联图像。

embed 方法接受两个参数

  • $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 变量将 $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!');
});

当传递字符串或整数作为第一个参数时，它将将其解释为 seconds。您还可以通过传递一个数组来指定时间，其中键是类型，值是数量。例如，从现在起 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 方法将活动添加到消息中。此方法接受单个 ID string 或 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 是一种允许您发布数据并通过浏览器显示的 Web 服务。这允许您快速确定实际发送到 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，但您也可以使用接口 BahriCanli\Mailgun\Contracts\Mailgun 在您的应用程序中进行依赖注入。

示例

namespace App\Http\Controllers;

class CustomController extends Controller
{

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

    /**
     * @param \BahriCanli\Mailgun\Contracts\Mailgun $mailgun
     */
    public function __construct(\BahriCanli\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. 使用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）。有关更多信息，请参阅许可文件