sales-sendgrid

SendGrid 平台帮助

帮助用户解答 SendGrid（Twilio）平台相关问题——涵盖通过 Email API 和 SMTP 中继发送事务性邮件、Marketing Campaigns、Dynamic Templates、Event Webhooks、Inbound Parse、域名验证、专用 IP、抑制列表、邮件测试和集成。

步骤 1 — 收集背景信息

如果存在 references/learnings.md，请先阅读，了解积累的知识。

询问用户：

1. 您需要 SendGrid 哪方面的帮助？

   • A) Email API — 通过 REST API 或 SMTP 中继发送事务性邮件、SDK
   • B) Marketing Campaigns — 拖放式编辑器、单次发送、自动化、注册表单
   • C) Dynamic Templates — 基于 Handlebars 的事务性模板、模板版本管理
   • D) 域名验证 — SPF/DKIM/DMARC 设置、品牌跟踪链接、反向 DNS
   • E) Event Webhooks — 投递事件、互动事件、Webhook 配置
   • F) Inbound Parse — 通过 Webhook 接收和解析入站邮件
   • G) Email Validation API — 地址验证、一次性域名检测
   • H) 专用 IP / 投递能力 — IP 预热、IP 池、发件人信誉
   • I) 抑制列表 — 退信、拦截、垃圾邮件报告、退订管理
   • J) 分析 / 统计 — 汇总统计、类别统计、邮箱服务商统计
   • K) 账户 / 账单 — 套餐、定价、子用户、团队成员、API 密钥
   • L) 其他 — 请描述

2. 您的角色是什么？

   • A) 开发者 / 工程师
   • B) 市场经理 / 邮件营销人员
   • C) DevOps / 基础设施人员
   • D) 管理员 / 账户所有者
   • E) 创始人 / 独立运营者
   • F) 代理商 / 自由职业者
   • G) 其他

3. 您想要实现什么？（请描述您的具体目标或问题）

如果用户的请求已经提供了大部分背景信息，请直接跳转到相关步骤。 根据合理假设（并明确说明）先尽力回答，然后只在最后询问最关键的 1-2 个澄清问题——不要因为需要收集完整背景信息而延迟回复。

注意：如果用户需要专业技能，请简要说明该技能更合适的原因，并引导他们前往相应技能。

步骤 2 — 转介或直接回答

如果请求对应某项专业技能，请转介：

• 通用邮件营销策略 / 最佳实践 -> /sales-email-marketing
• 跨平台邮件投递能力（非 SendGrid 特定）-> /sales-deliverability
• 邮件打开 / 点击跟踪策略 -> /sales-email-tracking
• 通过 Zapier 或中间件将 SendGrid 连接到其他工具 -> /sales-integration
• 漏斗策略 / 转化率优化 -> /sales-funnel

否则，请根据下方参考内容中的平台知识直接回答。

步骤 3 — SendGrid 平台参考

请阅读 references/platform-guide.md，了解详细的模块文档、定价、集成和数据模型。

您不再需要了解平台指南的详细内容——请专注于用户的具体情况。

第 4 步 — 可执行指南

根据用户的具体问题：

1. 通过 API 发送事务性邮件：

   1. 在 Settings > API Keys 中创建一个具有“Mail Send”权限的 API 密钥
   2. 在 Settings > Sender Authentication 中验证您的发送域名（将 CNAME 记录添加到您的 DNS）
   3. 安装您所用语言的 SDK（例如，Node.js 使用 npm install @sendgrid/mail）
   4. 设置 API 密钥：sgMail.setApiKey(process.env.SENDGRID_API_KEY)
   5. 编写并发送邮件：设置 to、from、subject、text/html（或 templateId + dynamicTemplateData）
   6. 处理响应 — 检查是否返回 202 Accepted（成功）或错误代码
   7. 设置 Event Webhooks，以跟踪投递和互动事件

2. 设置 Marketing Campaigns 自动化：

   1. 订阅 Marketing Campaigns 计划（自动化功能需要 Advanced 计划）
   2. 将联系人导入或添加到列表 — 使用 CSV 上传、注册表单或 Contacts API
   3. 前往 Automations > Create Automation
   4. 选择触发条件：欢迎系列（将新联系人添加到列表时）、基于日期的触发条件或自定义触发条件
   5. 构建邮件序列 — 添加邮件步骤，并设置步骤之间的延迟
   6. 使用拖放编辑器或代码编辑器设计每封邮件
   7. 激活自动化，并在自动化控制面板中监控进入率/完成率

3. 配置域名验证：

   1. 前往 Settings > Sender Authentication > Authenticate Your Domain
   2. 选择您的 DNS 托管服务商并输入您的发送域名
   3. SendGrid 会生成用于 SPF 和 DKIM 的 CNAME 记录 — 将这些记录添加到您的 DNS 服务商
   4. 在 SendGrid 中点击 Verify — 系统会检查 DNS 记录
   5. 设置品牌化跟踪链接（链接品牌化）— 添加另一个 CNAME 记录，用于点击/打开跟踪
   6. 如果使用专用 IP，请配置反向 DNS，将 IP 映射到您的域名
   7. 在您的 DNS 中单独设置 DMARC 记录（例如，v=DMARC1; p=quarantine; rua=mailto:[email protected]）

4. 设置 Event Webhooks：

   1. 前往 Settings > Mail Settings > Event Webhook
   2. 输入您的 Webhook URL（必须是可公开访问的 HTTPS 端点）
   3. 选择您希望接收的事件（processed、delivered、open、click、bounce 等）
   4. 启用 Webhook
   5. 在您的端点上使用 SendGrid 的公钥实施签名验证
   6. 处理传入的 JSON 事件对象数组 — 每个对象都包含 event、email、timestamp 和自定义参数
   7. 处理重试 — SendGrid 会在最长 24 小时内重试投递失败的事件

5. 设置 Inbound Parse：

   1. 为您的接收域名添加 MX 记录，并将其指向 mx.sendgrid.net
   2. 前往 Settings > Inbound Parse > Add Host & URL
   3. 输入您的接收域名和用于接收已解析邮件的 Webhook URL
   4. 选择原始（MIME）或已解析（结构化字段）格式
   5. 实施您的 Webhook 端点，以处理 multipart POST 数据（from、to、subject、body、attachments）
   6. 向您配置的域名下任意地址发送邮件进行测试

注意事项

根据研究尽力整理——请以 SendGrid 当前文档为准，核实相关细节。

1. Email API 和 Marketing Campaigns 是单独的订阅，计费也各自独立。 许多用户以为一个套餐就能涵盖所有功能。如果你既要发送事务性邮件（订单确认、密码重置），也要发送营销邮件（新闻简报、促销信息），就需要两个订阅。请相应地做好预算，并了解各项功能分别属于哪个套餐。
2. 免费试用仅限 60 天，且每天只能发送 100 封邮件——并非永久免费套餐。 与一些竞争对手不同，SendGrid 的免费服务会到期。60 天后，你必须升级到付费套餐，否则将无法发送邮件。请根据此限制规划评估和迁移时间。
3. 专用 IP 必须进行预热，否则会立即遇到送达率问题。 新的专用 IP 没有发送信誉。如果你使用尚未预热的 IP 发送大量邮件，邮箱服务提供商会限制或拒收你的邮件。请使用 SendGrid 的自动预热功能（默认启用），或制定手动预热计划，在 4-6 周内逐步从数百封提升到目标发送量。
4. 默认不会启用抑制组——如果不配置，退订将对所有邮件生效。 如果你没有配置抑制组（也称为“退订组”），任何退订操作都会将联系人从你的所有邮件列表中移除。请尽早设置抑制组（例如“Marketing”“Product Updates”“Billing Alerts”），让收件人可以选择退订特定类别，而不必停止接收所有通信。
5. Event Webhook 负载会批量发送，也可能延迟——不要将其用于实时逻辑。 SendGrid 会批量发送 Webhook 事件，可能延迟数秒到数分钟。如果你需要实时确认送达，请轮询 API，或使用 mail/send 响应代码（202 = 已接受处理）。设计 Webhook 消费端时，应确保其能够幂等地处理乱序和重复事件。
6. 重试时 sg_event_id 会变化——不要用它进行去重。 尽管文档称 sg_event_id 是“可用于去重的事件唯一 ID”，但每次重试时该 ID 都会变化。同一封邮件、同一事件、同一时间戳——但 sg_event_id 不同。请改用组合去重键：${sg_message_id}:${event}:${email}。将已处理的键存储在 Redis（设置 48 小时 TTL，以覆盖 SendGrid 的 24 小时重试窗口）或数据库中，并在处理每个事件前进行检查。
7. 共享 IP 信誉可能在毫无预警的情况下损害你的送达率。 在免费版/Essentials 套餐中，你会与其他发件人共享 IP。如果同一 IP 池中的恶意用户触发 Spamhaus 黑名单或 Microsoft 封锁，你的邮件也会受到影响——即便你的发件人评分达到 99%，且身份验证完美无误。SendGrid 官方表示，“通过共享 IP 池发送邮件时，遇到黑名单是正常现象。”如果你发现送达率莫名下降，请检查你的 IP 是否被列入黑名单（mxtoolbox.com），并考虑升级到专用 IP（Pro 套餐）。
8. Node.js SDK 不会复用 HTTP 连接——批量发送会导致套接字耗尽。 如果你并发调用大量 sgMail.send()，就会遇到 EMFILE 错误（文件描述符数量达到上限）。该 SDK 每次请求都会新建连接。请使用顺序发送（带 await 的 for...of）、并发限制器（将 p-limit 设为 2-10），或使用个性化收件人列表（单个请求最多 1000 位收件人），以减少连接数。
9. 通过一次 SDK 数组调用发送所有邮件，可能导致投递延迟数小时。 将数组传给 sgMail.send() 时，SendGrid 会在服务器端将邮件加入队列。对于有时效要求的发送，请使用个性化收件人列表（在一个请求中向不同收件人发送相同内容），或使用带并发控制的单独调用，而不要一次性提交超大批次。

• 持续改进：如果你发现此处未提及的问题，请将其附上今天的日期，追加到 references/learnings.md。

第 5 步 — 相关技能

• /sales-email-marketing — 电子邮件营销策略和最佳实践（不限平台）
• /sales-deliverability — 跨平台电子邮件送达能力——SPF/DKIM/DMARC、预热、收件箱投递
• /sales-email-tracking — 电子邮件打开和点击跟踪策略
• /sales-integration — 通过 Zapier、Make 或 API 将 SendGrid 连接到其他工具
• /sales-funnel — 漏斗策略和转化优化
• /sales-do — 不确定该使用哪项技能？路由器会将任何销售目标匹配到合适的技能。安装：npx skills add sales-skills/sales --skill sales-do

示例

示例 1：为 SaaS 应用设置事务性电子邮件

用户说：“我需要使用 SendGrid 从我的 Node.js 应用发送密码重置和欢迎邮件。” 技能会：

1. 引导创建仅具有“Mail Send”权限的受限 API 密钥，以确保安全
2. 指导设置域名身份验证——添加用于 SPF/DKIM 的 CNAME 记录
3. 展示如何安装 @sendgrid/mail，并通过环境变量配置 API 密钥
4. 在 SendGrid 界面中创建两个 Dynamic Templates——一个用于密码重置（包含 {{reset_link}}），另一个用于欢迎邮件（包含 {{first_name}}、{{login_url}}）
5. 提供使用 sgMail.send()、templateId 和 dynamicTemplateData 的代码示例
6. 建议设置 Event Webhooks，以跟踪投递失败并在邮件退回时触发警报 结果：用户获得了可用于生产环境的事务性电子邮件，包含模板、正确的身份验证和投递监控

示例 2：将营销邮件从 Mailchimp 迁移到 SendGrid

用户说：“我们要将简报从 Mailchimp 迁移到 SendGrid Marketing Campaigns。流程是什么？” 技能会：

1. 说明双重订阅模式——Marketing Campaigns 与 Email API 分开，因此用户需要选择合适的方案（Basic 或 Advanced）
2. 指导从 Mailchimp 导出联系人（CSV），并将其导入 SendGrid，同时映射字段
3. 提醒只能导入已订阅的联系人——导入前在 SendGrid 中重新创建抑制组
4. 指导使用 SendGrid 的拖放编辑器或代码编辑器重新创建电子邮件模板
5. 介绍 DNS 变更——移除 Mailchimp 的身份验证记录，并添加 SendGrid 用于 SPF/DKIM 的 CNAME 记录
6. 建议采用预热策略：从互动最活跃的联系人开始，逐步扩大范围，历时 2-4 周；如果使用新的专用 IP（Advanced 方案），尤其要遵循此策略 结果：用户获得了涵盖联系人、模板、DNS、抑制组和预热的迁移计划，以维持邮件送达能力

示例 3：设置 Event Webhooks 以跟踪投递

用户说：“我想跟踪哪些邮件被退回、哪些成功投递，以便更新我们的 CRM。” 技能会：

1. 指导配置 Event Webhook——选择 processed、delivered、deferred、bounce 和 dropped 事件
2. 指导实现一个接收 JSON 事件批次的 Webhook 端点
3. 说明如何使用 SendGrid 的公钥进行签名验证，以保护端点安全
4. 设计 CRM 更新逻辑：收到投递事件时将联系人标记为“已投递”，收到永久退信时标记为“无效”，收到延迟投递事件时将其加入重试队列
5. 提醒注意批量/延迟投递和重复事件——建议使用事件 sg_message_id 作为去重键，以实现幂等处理
6. 建议同时订阅打开和点击事件，以便在 CRM 中跟踪互动情况 结果：用户获得了一条 Webhook 流水线，可使其 CRM 与 SendGrid 的投递和互动事件保持同步

故障排除

切换到专用 IP 后邮件进入垃圾邮件文件夹

症状：升级到 Pro 或 Advanced 套餐并使用专用 IP 后不久，邮件送达率下降，邮件开始进入垃圾邮件文件夹
原因：专用 IP 是新的，没有发送声誉。邮箱服务提供商（Gmail、Yahoo、Outlook）会谨慎对待未知 IP，并会限制来自这些 IP 的邮件，或将其放入垃圾邮件文件夹。
解决方案：在 Settings > IP Addresses 中启用自动 IP 预热（新 IP 默认应已启用）。如果你已将其关闭，请重新启用。预热期间，SendGrid 会将流量分配到新的专用 IP 和共享 IP 池，数周内逐步将流量转移到专用 IP。不要在尚未预热的 IP 上发送全部邮件。如果送达率已经受损，请暂停高流量发送，重新启用预热，并从互动度最高的收件人开始发送。监控邮箱服务提供商的统计数据，查看哪些提供商正在拒收邮件。请参阅 /sales-deliverability，了解全面的预热指南。

Event Webhook 未接收事件

症状：你配置了 Event Webhook URL，但端点没有收到任何事件数据
原因：Webhook URL 无法公开访问、HTTPS 证书无效、端点返回非 2xx 状态码，或 Webhook 未启用。
解决方案：在 Settings > Mail Settings > Event Webhook 中确认 Webhook 已启用。确保 URL 可从公网访问（不是 localhost，也没有被防火墙拦截）。检查 HTTPS 证书是否有效且不是自签名证书。手动向端点发送包含示例 JSON 的 POST 请求进行测试。检查端点是否在 3 秒内返回 2xx 状态码——SendGrid 会将超时和错误视为失败并重试，但最终会在 24 小时后停止重试。可使用 ngrok 等工具进行本地开发测试。查看 SendGrid 的 Event Webhook 活动日志，了解投递尝试和错误代码。

Gmail/Yahoo 因 DMARC 对齐错误拦截邮件

症状：邮件被延迟或拒收，并显示 421 4.7.32 From: header isn't aligned with either the authenticated SPF or DKIM organizational domain——定时发送的邮件尤其常见
原因：From 地址的域名与在 SendGrid 中验证的域名不匹配。例如，通过 SendGrid 使用 gmail.com 地址发送邮件，或仅验证了 notifications.example.com，却使用 [email protected] 发送邮件。自 2024 年 2 月以来，Gmail 和 Yahoo 严格执行 DMARC 对齐要求。
解决方案：前往 Settings > Sender Authentication > Authenticate Your Domain，验证你实际发送邮件所用的确切域名。将 SendGrid 生成的 CNAME 记录添加到 DNS。确保 From 地址匹配——如果你验证的是 example.com，则可使用 [email protected] 发送邮件。在 DNS 中添加 DMARC 记录：v=DMARC1; p=none; rua=mailto:[email protected]（先使用 p=none 进行监控）。如果你使用的是共享 IP 套餐，修复身份验证后仍遇到流量限制，共享 IP 可能声誉不佳——请在 mxtoolbox.com 上检查，并考虑使用专用 IP（Pro 套餐）。

Webhook 事件去重失败——数据库中出现重复条目

症状：即使检查了 sg_event_id，仍处理了重复的 Webhook 事件——相同的邮件、相同的事件类型、相同的时间戳，但 sg_event_id 值不同
原因：每次重试时，sg_event_id 都会变化。尽管文档称其为去重键，但它对每次投递尝试唯一，而非对每个逻辑事件唯一。
解决方案：使用重试期间保持稳定的字段构建复合去重键：${sg_message_id}:${event}:${email}。将已处理的键存储在 Redis 中，并设置 48 小时的 TTL（覆盖 SendGrid 24 小时的重试窗口并留有余量），或者存储在带有唯一约束的数据库表中。处理每个事件前先进行检查。对于高流量系统，可使用布隆过滤器或带有 EXPIRE 的 Redis SET，以便快速查找。

发送批量邮件时出现 EMFILE 错误 / 套接字耗尽

症状：发送数百或数千封邮件时出现 Error: connect EMFILE — 通常前几批发送成功，之后的批次失败 原因：每次调用 sgMail.send() 都会打开一个新的 HTTP 连接。Node.js 的默认文件描述符限制约为 1024。并发请求会在先前的连接关闭前耗尽可用套接字。SendGrid Node SDK 不会对连接进行池化。 解决方案：有三种方法（任选其一）：(1) 按顺序发送：for (const msg of messages) { await sgMail.send(msg); } — 速度最慢，但最简单。(2) 限制并发数：使用 p-limit，将并发请求数设为 2 到 10：const limit = pLimit(5); await Promise.all(msgs.map(m => limit(() => sgMail.send(m))));。(3) 使用个性化设置：如果收件人收到的内容相同，仅替换数据不同，可通过 personalizations 数组在单次 API 调用中向最多 1000 位收件人发送邮件 — 这是效率最高的方法，并且只使用一个 HTTP 连接。

营销联系人未显示在细分中

症状：通过 API 导入或添加的联系人未按预期显示在细分或列表中 原因：Marketing Campaigns 中的联系人摄取是异步的 — 联系人可能需要几分钟到几小时才能完成索引并显示在细分中。此外，导入也可能因字段无效或重复联系人处理而部分失败。 解决方案：前往 Marketing > Contacts > Imports，检查导入状态是否有错误或警告。对于大型导入，请等待最多 2 小时，以便完成索引。确认导入中的自定义字段名称与 SendGrid 账户中定义的自定义字段一致（不匹配会导致字段被静默丢弃）。在界面中搜索特定联系人，检查其字段值是否符合预期。对于通过 API 添加的联系人（PUT /v3/marketing/contacts），请检查响应中的 job_id，并轮询 GET /v3/marketing/contacts/imports/{id} 查看状态。如果联系人出现在列表中，但未出现在细分中，请检查细分查询条件 — 确保字段名称和运算符与实际联系人数据相符。