Laravel 对接 SendGrid 发送邮件

Laravel 对接 SendGrid 发送邮件

一、前期准备：SendGrid 账户与 API 密钥配置

1. 注册并配置 SendGrid 账户

• 访问 SendGrid 官网 完成注册，新用户可享受每月 100 封免费邮件额度
• 登录后进入控制台，完成账户验证（邮箱验证和手机号验证）

2. 创建 API 密钥

API 密钥是 Laravel 与 SendGrid 通信的核心凭证，创建步骤：

1. 进入 Settings > API Keys 菜单
2. 点击 Create API Key 按钮
3. 选择密钥权限：
   • 测试环境：建议选择「Full Access」
   • 生产环境：推荐按最小权限原则，至少保留「Mail Send」权限
4. 生成后立即复制密钥（仅显示一次），妥善保存

二、Laravel 项目基础配置

1. 安装 SendGrid PHP 库

通过 Composer 安装官方 SDK：

bash

composer require sendgrid/sendgrid

2. 配置环境变量

编辑项目根目录的 .env 文件，添加 SendGrid 相关配置：

env

# 邮件驱动配置
MAIL_MAILER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your_sendgrid_api_key  # 替换为实际API密钥
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your_verified_email@example.com  # 已验证的发件邮箱
MAIL_FROM_NAME="${APP_NAME}"  # 发件人名称

三、发送邮件的三种实现方式

1. 使用 Mail Facade 发送简单邮件

php

use Illuminate\Support\Facades\Mail;

// 发送纯文本邮件
Mail::raw('这是通过SendGrid发送的测试邮件', function ($message) {
    $message->to('recipient@example.com')
            ->subject('测试邮件');
});

2. 发送带视图的 HTML 邮件

3. 创建视图文件 resources/views/emails/welcome.blade.php：

html

<h1>欢迎注册 {{ $appName }}</h1>
<p>尊敬的 {{ $userName }}，感谢您的注册！</p>

1. 发送邮件：

php

Mail::send('emails.welcome', [
    'appName' => config('app.name'),
    'userName' => '测试用户'
], function ($message) {
    $message->to('user@example.com')
            ->subject('欢迎注册通知');
});

3. 使用自定义邮件类（推荐）

4. 生成邮件类：

bash

php artisan make:mail WelcomeEmail

1. 编辑邮件类 app/Mail/WelcomeEmail.php：

php

namespace App\Mail;

use Illuminate\Mail\Mailable;

class WelcomeEmail extends Mailable
{
    use Queueable, SerializesModels;
    
    public $user;
    
    public function __construct($user)
    {
        $this->user = $user;
    }
    
    public function build()
    {
        return $this->view('emails.welcome')
                    ->subject('欢迎加入我们');
    }
}

1. 发送邮件：

php

use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;

$user = User::find(1);
Mail::to($user->email)->send(new WelcomeEmail($user));

四、发件人验证配置（必做）

1. 单个发件人验证（测试环境）

2. 进入 SendGrid 控制台 Settings > Sender Authentication

3. 选择 Single Sender Verification

4. 填写邮箱信息并提交，点击验证邮件中的链接完成验证

5. 域名验证（生产环境推荐）

6. 进入 Sender Authentication > Domain Authentication

7. 输入域名并选择解析类型（推荐 CNAME）

8. 在域名解析商处添加指定的 TXT、CNAME 记录

9. 等待 SendGrid 自动验证（通常 10-30 分钟）

五、高级功能：使用 SendGrid API

1. 创建 SendGrid 服务类

php

namespace App\Services;

use SendGrid;
use SendGrid\Mail\Mail;

class SendGridService
{
    public function sendWithTemplate($to, $templateId, $data)
    {
        $email = new Mail();
        $email->setFrom(env('MAIL_FROM_ADDRESS'), env('MAIL_FROM_NAME'));
        $email->addTo($to);
        $email->setTemplateId($templateId);
        $email->addDynamicTemplateDatas($data);
        
        $sendgrid = new SendGrid(env('MAIL_PASSWORD'));
        return $sendgrid->send($email);
    }
}

2. 使用服务类发送模板邮件

php

$service = new \App\Services\SendGridService();
$service->sendWithTemplate(
    'user@example.com',
    'd-xxxxxxxxxxxxxxx',  // 模板ID
    ['username' => 'testuser']  // 模板变量
);

六、状态追踪与 Webhook 配置

1. 主动查询发送状态

php

public function getEmailStatus($messageId)
{
    $sendgrid = new SendGrid(env('MAIL_PASSWORD'));
    $response = $sendgrid->client->messages($messageId)->get();
    return json_decode($response->body());
}

2. 配置 Webhook 接收实时通知

3. 在 SendGrid 控制台配置 Webhook 地址：https://your-domain.com/sendgrid/webhook

4. 创建接收控制器：

php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class SendGridWebhookController extends Controller
{
    public function handle(Request $request)
    {
        $events = $request->json()->all();
        foreach ($events as $event) {
            // 处理事件：打开、点击、退信等
            \Log::info('SendGrid event', $event);
        }
        return response('OK', 200);
    }
}

七、注意事项与最佳实践

• 生产环境建议使用队列处理邮件发送：Mail::to(...)->queue(...)
• 定期清理无效邮箱，避免影响发送信誉
• 监控 SendGrid 控制台的送达率和退信率
• 遵循邮件发送频率限制，避免触发反垃圾机制