如何在 PHP 中通过Composer安装 PHP-Mailgun 库通过 API 发送大规模营销邮件-composer-PHP中文网

不推荐用 php-mailgun 库发大规模营销邮件，因其仅为轻量级 api 封装，无队列、重试、节流及批量能力，易触发 mailgun 速率限制或封禁 api key；正确做法是直接调用 mailgun 批量接口（如 /messages）并配合异步队列系统。

如何在 php 中通过composer安装 php-mailgun 库通过 api 发送大规模营销邮件

直接说结论：不推荐用 php-mailgun 库发大规模营销邮件，它本质是轻量级封装，没内置队列、重试、节流或批量发送能力，强行用会触发 Mailgun 的速率限制甚至封禁 API key。

为什么 `php-mailgun` 不适合营销邮件场景

这个库只是对 Mailgun HTTP API 的简单 cURL 封装，send() 方法每次调用都发起一次同步请求，没有：

自动分批（Mailgun 单次 /messages 接口最多收 1000 个收件人）
失败后指数退避重试（比如临时 429 或 503）
连接池或并发控制（并发开太高会被限流）
收件人去重、硬/软退信处理逻辑

你用它循环发 10 万封，大概率在第 3000 封左右收到 429 Too Many Requests，然后整个流程卡死。

正确做法：用 Mailgun 官方推荐的批量接口 + 队列驱动

营销邮件必须走 Mailgun 的 /messages.mime（发原始 MIME）或更稳妥的 /messages 批量模式，并配合异步任务系统。实操建议如下：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

用 guzzlehttp/guzzle 直接调用 Mailgun API，别套一层 php-mailgun
收件人列表按每 900 人一组切片（留 100 余量防字段膨胀）
每组构造一个含 to 数组的 JSON 请求体，POST 到 https://api.mailgun.net/v3/YOUR_DOMAIN/messages
PHP 侧用 symfony/messenger 或 laravel/framework 的队列推任务，Worker 进程里执行发送
务必在请求头加 Authorization: Basic {base64(api:key-xxx)}，别依赖库自动拼

示例关键片段：

$client = new \GuzzleHttp\Client();
$response = $client->post('https://api.mailgun.net/v3/yourdomain.com/messages', [
    'auth' => ['api', 'key-xxxxxxxxxx'],
    'form_params' => [
        'from' => 'news@yourdomain.com',
        'to' => ['a@example.com', 'b@example.com'],
        'subject' => 'Weekly Digest',
        'html' => '<h1>Hello</h1>'
    ]
]);

Composer 安装和基础配置陷阱

即使你坚持要用 php-mailgun，也得避开几个坑：

别装 php-mailgun/php-mailgun —— 这个包已三年未更新，不兼容 PHP 8.1+，且依赖过时的 guzzlehttp/guzzle ~5.0
改用社区维护的 mailgun/mailgun-php：composer require mailgun/mailgun-php
初始化时必须显式传入 HttpClient 实例，否则默认用 Guzzle 6，但新版 Mailgun API 要求 User-Agent 头含版本号，否则返回 400 Bad Request
setApiEndpoint() 必须设为 https://api.mailgun.net，不能漏掉 /v3 —— 它不是路径而是 API 版本前缀