Laravel 對接 SendGrid 發(fā)送郵件
Laravel 對接 SendGrid 發(fā)送郵件
一、前期準(zhǔn)備：SendGrid 賬戶與 API 密鑰配置
- 注冊并配置 SendGrid 賬戶
- 訪問 SendGrid 官網(wǎng) 完成注冊，新用戶可享受每月 100 封免費(fèi)郵件額度
- 登錄后進(jìn)入控制臺，完成賬戶驗(yàn)證（郵箱驗(yàn)證和手機(jī)號驗(yàn)證）
- 創(chuàng)建 API 密鑰
API 密鑰是 Laravel 與 SendGrid 通信的核心憑證，創(chuàng)建步驟：
- 進(jìn)入 Settings > API Keys 菜單
- 點(diǎn)擊 Create API Key 按鈕
- 選擇密鑰權(quán)限：
- 測試環(huán)境：建議選擇「Full Access」
- 生產(chǎn)環(huán)境：推薦按最小權(quán)限原則，至少保留「Mail Send」權(quán)限
- 生成后立即復(fù)制密鑰（僅顯示一次），妥善保存
二、Laravel 項(xiàng)目基礎(chǔ)配置
- 安裝 SendGrid PHP 庫
通過 Composer 安裝官方 SDK：
bash
composer require sendgrid/sendgrid
- 配置環(huán)境變量
編輯項(xiàng)目根目錄的 .env 文件，添加 SendGrid 相關(guān)配置：
env
# 郵件驅(qū)動配置
MAIL_MAILER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your_sendgrid_api_key # 替換為實(shí)際API密鑰
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your_verified_email@example.com # 已驗(yàn)證的發(fā)件郵箱
MAIL_FROM_NAME="${APP_NAME}" # 發(fā)件人名稱
三、發(fā)送郵件的三種實(shí)現(xiàn)方式
- 使用 Mail Facade 發(fā)送簡單郵件
php
use Illuminate\Support\Facades\Mail;
// 發(fā)送純文本郵件
Mail::raw('這是通過SendGrid發(fā)送的測試郵件', function ($message) {
$message->to('recipient@example.com')
->subject('測試郵件');
});
-
發(fā)送帶視圖的 HTML 郵件
-
創(chuàng)建視圖文件 resources/views/emails/welcome.blade.php：
html
<h1>歡迎注冊 {{ $appName }}</h1>
<p>尊敬的 {{ $userName }}，感謝您的注冊！</p>
- 發(fā)送郵件：
php
Mail::send('emails.welcome', [
'appName' => config('app.name'),
'userName' => '測試用戶'
], function ($message) {
$message->to('user@example.com')
->subject('歡迎注冊通知');
});
-
使用自定義郵件類（推薦）
-
生成郵件類：
bash
php artisan make:mail WelcomeEmail
- 編輯郵件類 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('歡迎加入我們');
}
}
- 發(fā)送郵件：
php
use App\Mail\WelcomeEmail;
use Illuminate\Support\Facades\Mail;
$user = User::find(1);
Mail::to($user->email)->send(new WelcomeEmail($user));
四、發(fā)件人驗(yàn)證配置（必做）
-
單個(gè)發(fā)件人驗(yàn)證（測試環(huán)境）
-
進(jìn)入 SendGrid 控制臺 Settings > Sender Authentication
-
選擇 Single Sender Verification
-
填寫郵箱信息并提交，點(diǎn)擊驗(yàn)證郵件中的鏈接完成驗(yàn)證
-
域名驗(yàn)證（生產(chǎn)環(huán)境推薦）
-
進(jìn)入 Sender Authentication > Domain Authentication
-
輸入域名并選擇解析類型（推薦 CNAME）
-
在域名解析商處添加指定的 TXT、CNAME 記錄
-
等待 SendGrid 自動驗(yàn)證（通常 10-30 分鐘）
五、高級功能：使用 SendGrid API
- 創(chuàng)建 SendGrid 服務(wù)類
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);
}
}
- 使用服務(wù)類發(fā)送模板郵件
php
$service = new \App\Services\SendGridService();
$service->sendWithTemplate(
'user@example.com',
'd-xxxxxxxxxxxxxxx', // 模板ID
['username' => 'testuser'] // 模板變量
);
六、狀態(tài)追蹤與 Webhook 配置
- 主動查詢發(fā)送狀態(tài)
php
public function getEmailStatus($messageId)
{
$sendgrid = new SendGrid(env('MAIL_PASSWORD'));
$response = $sendgrid->client->messages($messageId)->get();
return json_decode($response->body());
}
-
配置 Webhook 接收實(shí)時(shí)通知
-
在 SendGrid 控制臺配置 Webhook 地址：https://your-domain.com/sendgrid/webhook
-
創(chuàng)建接收控制器：
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) {
// 處理事件：打開、點(diǎn)擊、退信等
\Log::info('SendGrid event', $event);
}
return response('OK', 200);
}
}
七、注意事項(xiàng)與最佳實(shí)踐
- 生產(chǎn)環(huán)境建議使用隊(duì)列處理郵件發(fā)送：Mail::to(...)->queue(...)
- 定期清理無效郵箱，避免影響發(fā)送信譽(yù)
- 監(jiān)控 SendGrid 控制臺的送達(dá)率和退信率
- 遵循郵件發(fā)送頻率限制，避免觸發(fā)反垃圾機(jī)制
浙公網(wǎng)安備 33010602011771號