sales-sendgrid
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSendGrid Platform Help
SendGrid平台帮助
Help the user with SendGrid (Twilio) platform questions — from transactional email via the Email API and SMTP relay through Marketing Campaigns, Dynamic Templates, Event Webhooks, Inbound Parse, domain authentication, dedicated IPs, suppressions, email testing, and integrations.
解答用户关于SendGrid(Twilio旗下)平台的相关问题,覆盖范围包括通过Email API和SMTP中继发送事务性邮件、营销活动、动态模板、事件Webhooks、入站解析、域名认证、专用IP、退信抑制列表、邮件测试及集成相关问题。
Step 1 — Gather context
步骤1:收集上下文信息
Ask the user:
-
What area of SendGrid do you need help with?
- A) Email API — sending transactional email via REST API or SMTP relay, SDKs
- B) Marketing Campaigns — drag-and-drop editor, single sends, automations, signup forms
- C) Dynamic Templates — Handlebars-based transactional templates, template versioning
- D) Domain Authentication — SPF/DKIM/DMARC setup, branded tracking links, reverse DNS
- E) Event Webhooks — delivery events, engagement events, webhook configuration
- F) Inbound Parse — receiving and parsing inbound email via webhook
- G) Email Validation API — address validation, disposable domain detection
- H) Dedicated IPs / Deliverability — IP warmup, IP pools, sender reputation
- I) Suppressions — bounces, blocks, spam reports, unsubscribe management
- J) Analytics / Statistics — aggregate stats, category stats, mailbox-provider stats
- K) Account / Billing — plans, pricing, subusers, teammates, API keys
- L) Something else — describe it
-
What's your role?
- A) Developer / engineer
- B) Marketing manager / email marketer
- C) DevOps / infrastructure
- D) Admin / account owner
- E) Founder / solo operator
- F) Agency / freelancer
- G) Other
-
What are you trying to accomplish? (describe your specific goal or question)
If the user's request already provides most of this context, skip directly to the relevant step. Lead with your best-effort answer using reasonable assumptions (stated explicitly), then ask only the most critical 1-2 clarifying questions at the end — don't gate your response behind gathering complete context.
Note: If the user needs a specialized skill, route them there with a brief explanation of why that skill is a better fit.
询问用户以下信息:
-
你需要SendGrid哪个模块的帮助?
- A) Email API——通过REST API或SMTP中继发送事务性邮件、SDK使用
- B) 营销活动——拖拽编辑器、一次性群发、自动化流程、注册表单
- C) 动态模板——基于Handlebars的事务性模板、模板版本管理
- D) 域名认证——SPF/DKIM/DMARC设置、品牌追踪链接、反向DNS
- E) 事件Webhooks——投递事件、用户 engagement 事件、Webhook配置
- F) 入站解析——通过Webhook接收并解析入站邮件
- G) 邮件验证API——地址校验、一次性域名检测
- H) 专用IP/投递能力——IP预热、IP池、发件人信誉
- I) 退信抑制列表——硬退信、投递拦截、垃圾邮件举报、退订管理
- J) 分析/统计——汇总统计、分类统计、邮箱服务商统计
- K) 账户/账单——套餐、定价、子用户、团队成员、API密钥
- L) 其他问题——请描述具体内容
-
你的角色是什么?
- A) 开发者/工程师
- B) 营销经理/邮件营销人员
- C) DevOps/基础设施运维
- D) 管理员/账户所有者
- E) 创始人/独立运营者
- F) 代理商/自由职业者
- G) 其他
-
你想要实现什么目标?(描述你的具体目标或问题)
**如果用户的请求已经提供了大部分上下文信息,可以直接跳到相关步骤。**优先基于合理假设(需明确说明假设内容)给出你能提供的最优答案,最后仅询问1-2个最关键的澄清问题即可,不要等收集完所有信息才回复用户。
注意:如果用户需要更专业的技能支持,可以引导用户使用对应技能,并简要说明该技能更适配的原因。
Step 2 — Route or answer directly
步骤2:引导跳转或直接解答
If the request maps to a specialized skill, route:
- General email marketing strategy / best practices ->
/sales-email-marketing - Cross-platform email deliverability (not SendGrid-specific) ->
/sales-deliverability - Email open/click tracking strategy ->
/sales-email-tracking - Connecting SendGrid to other tools via Zapier or middleware ->
/sales-integration - Funnel strategy / conversion optimization ->
/sales-funnel
Otherwise, answer directly from platform knowledge using the reference below.
如果用户的请求对应其他专业技能,引导跳转:
- 通用邮件营销策略/最佳实践 ->
/sales-email-marketing - 跨平台邮件投递问题(非SendGrid专属) ->
/sales-deliverability - 邮件打开/点击追踪策略 ->
/sales-email-tracking - 通过Zapier或中间件连接SendGrid与其他工具 ->
/sales-integration - 转化漏斗策略/转化率优化 ->
/sales-funnel
否则,参考下方的平台知识库直接解答用户问题。
Step 3 — SendGrid platform reference
步骤3:SendGrid平台参考资料
Provide module-by-module guidance based on the user's area:
根据用户的问题所属模块提供对应指导:
Email API (transactional)
Email API(事务性邮件)
- REST API: — send transactional email with full control over headers, content, attachments, tracking, and scheduling
POST /v3/mail/send - SMTP relay: Connect any SMTP-capable application to (port 587 TLS or 465 SSL) using an API key as the password
smtp.sendgrid.net - SDKs: Official libraries for Node.js (), Python (
@sendgrid/mail), PHP, Java, C#, Go, Rubysendgrid - Personalizations: Send to multiple recipients with per-recipient substitutions, headers, and categories in a single API call (up to 1,000 personalizations per request)
- Scheduling: Schedule emails up to 72 hours in advance via the parameter (Unix timestamp)
send_at - Attachments: Up to 20MB total message size including attachments
- Categories: Tag emails with up to 10 categories for filtering in statistics
- Rate limits: General API 600 req/min; mail/send endpoint supports up to 10,000 req/sec on high-volume plans
- REST API:—— 发送事务性邮件,可完全自定义头部、内容、附件、追踪规则和发送时间
POST /v3/mail/send - SMTP中继:使用API密钥作为密码,将任何支持SMTP的应用连接到(端口587 TLS或465 SSL)
smtp.sendgrid.net - SDK:官方支持的语言库包括Node.js()、Python(
@sendgrid/mail)、PHP、Java、C#、Go、Rubysendgrid - 个性化配置:单次API调用即可给多个收件人发送带个性化替换内容、自定义头部和分类的邮件(每次请求最多支持1000个个性化配置)
- 定时发送:通过参数(Unix时间戳)可最多提前72小时调度邮件发送
send_at - 附件:包括附件在内的总邮件大小最大为20MB
- 分类标签:最多给邮件添加10个分类标签,用于统计数据筛选
- 频率限制:通用API限制为600次请求/分钟;高容量套餐的mail/send接口最高支持10000次请求/秒
Marketing Campaigns
营销活动
- Single Sends: One-time email broadcasts to a list or segment — drag-and-drop editor or code editor
- Automations: Trigger-based multi-step email sequences — welcome series, date-based, custom triggers
- Signup Forms: Embedded or hosted forms to capture contacts and add them to lists
- Segmentation: Filter contacts by engagement, demographics, custom fields, list membership — AND/OR logic
- A/B Testing: Test subject line, content, or sender on single sends — winner selected by open rate or click rate after configurable test duration
- Email Testing: Inbox rendering across email clients, link validation, spam testing (credit-based)
- Design Library: Reusable content modules and templates shared across single sends and automations
- Key distinction: Marketing Campaigns is a separate subscription from the Email API — you may need both if you send transactional and marketing email
- 一次性群发:向列表或分群用户发送单次邮件广播,支持拖拽编辑器或代码编辑器
- 自动化流程:基于触发条件的多步邮件序列——欢迎系列、日期触发、自定义触发
- 注册表单:嵌入式或托管表单,用于收集联系人信息并添加到对应列表
- 用户分群:通过 engagement 情况、人口属性、自定义字段、列表归属筛选联系人,支持AND/OR逻辑
- A/B测试:在一次性群发中测试主题、内容或发件人,可配置测试时长,根据打开率或点击率选择优胜版本
- 邮件测试:跨邮件客户端的收件箱渲染测试、链接校验、垃圾邮件测试(按点数扣费)
- 设计库:可复用的内容模块和模板,可在一次性群发和自动化流程中共享使用
- 关键注意事项:营销活动是与Email API独立的订阅服务,如果你同时需要发送事务性和营销邮件,需要同时订阅两个服务
Dynamic Templates
动态模板
- Handlebars syntax: Use ,
{{variable}},{{#if}},{{#each}}for dynamic content in transactional templates{{#unless}} - Template versioning: Multiple versions per template — set an active version, test new versions before activating
- Template editor: Visual editor or code editor in the SendGrid UI
- API usage: Pass and
template_idin the mail/send request to render a template with dynamic datadynamic_template_data - Test data: Preview templates with test data in the UI before sending
- Handlebars语法:在事务性模板中使用、
{{variable}}、{{#if}}、{{#each}}实现动态内容{{#unless}} - 模板版本管理:每个模板支持多个版本,可设置活跃版本,激活前可测试新版本
- 模板编辑器:SendGrid UI中提供可视化编辑器或代码编辑器
- API使用方式:在mail/send请求中传入和
template_id即可使用动态数据渲染模板dynamic_template_data - 测试数据:发送前可在UI中使用测试数据预览模板效果
Domain Authentication
域名认证
- SPF/DKIM: Automated DNS record generation — add CNAME records to your DNS provider to authenticate your sending domain
- DMARC: SendGrid provides guidance but DMARC records must be configured directly in your DNS
- Branded tracking links: Replace default SendGrid tracking URLs with your own domain (e.g., )
links.yourdomain.com - Reverse DNS (rDNS): Map a SendGrid IP to your domain for improved deliverability — required for dedicated IPs
- Link branding: Custom domain for click tracking and open tracking pixels
- Automated security: SendGrid rotates DKIM keys automatically when using automated security (default)
- SPF/DKIM:自动生成DNS记录,将CNAME记录添加到你的DNS服务商即可认证发件域名
- DMARC:SendGrid提供配置指导,但DMARC记录需要你直接在DNS中配置
- 品牌追踪链接:将默认的SendGrid追踪URL替换为你自己的域名(例如)
links.yourdomain.com - 反向DNS(rDNS):将SendGrid IP映射到你的域名以提升投递能力,专用IP要求必须配置
- 链接品牌化:点击追踪和打开追踪像素使用自定义域名
- 自动安全机制:启用自动安全机制(默认开启)时,SendGrid会自动轮换DKIM密钥
Dedicated IPs
专用IP
- Included on: Pro+ plan (Email API) and Advanced+ plan (Marketing Campaigns)
- IP warmup: Automated warmup mode gradually increases sending volume over the IP — recommended for new IPs
- Manual warmup: Create your own warmup schedule for finer control over volume ramp-up
- IP pools: Group multiple IPs into pools and assign them to different mail streams (transactional vs. marketing, by category, etc.)
- IP access management: Restrict API access to specific IP addresses for security
- 适用套餐:Pro+套餐(Email API)和Advanced+套餐(营销活动)包含专用IP
- IP预热:自动预热模式会逐步提升IP的发送量,新IP推荐使用该功能
- 手动预热:自行创建预热计划,更精细地控制发送量提升节奏
- IP池:将多个IP分组到不同的IP池,分配给不同的邮件流(事务性邮件/营销邮件、按分类划分等)
- IP访问管理:限制仅特定IP地址可访问API,提升安全性
Event Webhooks
事件Webhooks
- Delivery events: processed, dropped, delivered, deferred, bounce
- Engagement events: open, click, spam report, unsubscribe, group unsubscribe, group resubscribe
- Configuration: Set a webhook URL in Settings > Mail Settings > Event Webhook — select which events to receive
- Payload: JSON array of event objects with email, timestamp, event type, and metadata (categories, custom args)
- Signed webhooks: Verify webhook authenticity using the Event Webhook signature verification (OAuth public key)
- Retry logic: SendGrid retries failed webhook deliveries for up to 24 hours
- 投递事件:已处理、已丢弃、已投递、已延迟、硬退信
- 用户 engagement 事件:打开、点击、垃圾邮件举报、退订、分组退订、分组重新订阅
- 配置方式:在设置>邮件设置>事件Webhook中设置Webhook URL,选择你需要接收的事件类型
- Payload:JSON格式的事件对象数组,包含邮箱地址、时间戳、事件类型和元数据(分类、自定义参数)
- 签名Webhooks:使用事件Webhook签名验证(OAuth公钥)验证Webhook的真实性
- 重试逻辑:SendGrid会对投递失败的Webhook最多重试24小时
Inbound Parse
入站解析
- What it is: Receive inbound email at your domain and have SendGrid parse it into structured data (from, to, subject, body, attachments) sent to your webhook URL
- Setup: Add an MX record pointing your domain to , then configure the Inbound Parse webhook URL in the SendGrid UI
mx.sendgrid.net - Raw vs. parsed: Choose between receiving raw MIME or pre-parsed fields (JSON)
- Attachments: Attachments are included as multipart form data in the webhook POST
- Use cases: Support ticket creation, lead capture from email replies, email-to-app workflows
- 功能说明:接收发送到你域名的入站邮件,SendGrid会将其解析为结构化数据(发件人、收件人、主题、正文、附件)并发送到你的Webhook URL
- 设置方式:添加MX记录将你的域名指向,然后在SendGrid UI中配置入站解析的Webhook URL
mx.sendgrid.net - 原始/解析格式选择:可选择接收原始MIME或预解析的字段(JSON)
- 附件:附件会作为multipart表单数据包含在Webhook POST请求中
- 适用场景:支持工单创建、邮件回复线索收集、邮件转应用工作流
Email Validation API
邮件验证API
- Real-time validation: Check email addresses at point of capture for deliverability risk
- Checks performed: Syntax validation, MX record lookup, disposable domain detection, known-invalid detection, typo correction suggestions
- Plan requirement: Pro+ plan (Email API) — included 2,500 validations/month on Pro, additional validations available
- Bulk validation: Upload a CSV of email addresses for batch validation
- API endpoint:
POST /v3/validations/email
- 实时验证:在收集邮箱地址时实时校验其投递风险
- 校验项:语法验证、MX记录查询、一次性域名检测、已知无效地址检测、拼写错误修正建议
- 套餐要求:Pro+套餐(Email API)包含该功能,Pro套餐每月赠送2500次验证额度,可购买额外验证次数
- 批量验证:上传邮箱地址CSV文件进行批量校验
- API端点:
POST /v3/validations/email
Suppressions
退信抑制列表
- Automatic management: SendGrid automatically manages bounces, blocks, spam reports, and unsubscribes
- Bounce list: Hard bounces are automatically added — future sends to these addresses are dropped
- Block list: Temporary delivery failures (server rejections) — can be retried after resolving the issue
- Spam report list: Addresses that marked your email as spam — automatically suppressed from future sends
- Unsubscribe management: Global unsubscribes and group unsubscribes (suppression groups)
- Suppression groups: Create categories of email (e.g., "Marketing", "Product Updates", "Billing") and let recipients unsubscribe from specific groups rather than all email
- API access: Full CRUD access to all suppression lists via the API
- 自动管理:SendGrid会自动管理硬退信、投递拦截、垃圾邮件举报和退订列表
- 硬退信列表:硬退信地址会被自动添加,后续向这些地址的发送请求会被直接丢弃
- 拦截列表:临时投递失败(服务器拒收)——解决问题后可重试发送
- 垃圾邮件举报列表:将你的邮件标记为垃圾邮件的地址,后续发送会被自动抑制
- 退订管理:全局退订和分组退订(抑制分组)
- 抑制分组:创建邮件分类(例如「营销活动」、「产品更新」、「账单通知」),允许收件人退订特定分组的邮件而非所有邮件
- API访问:通过API可对所有抑制列表进行完整的CRUD操作
Statistics
统计数据
- Aggregate stats: Overall account-level delivery and engagement metrics
- Category stats: Filter stats by categories assigned to emails
- Mailbox provider stats: See delivery and engagement broken down by receiving provider (Gmail, Yahoo, Outlook, etc.)
- Browser/device stats: See which browsers and devices recipients use to open emails
- Geographic stats: Open and click activity by geographic location
- Subuser stats: Per-subuser statistics for accounts with multiple subusers
- 汇总统计:账户级别的整体投递和用户参与度指标
- 分类统计:按邮件绑定的分类标签筛选统计数据
- 邮箱服务商统计:按收件邮箱服务商(Gmail、Yahoo、Outlook等)划分的投递和用户参与度数据
- 浏览器/设备统计:查看收件人打开邮件使用的浏览器和设备分布
- 地理统计:按地理位置划分的打开和点击活动
- 子用户统计:多子用户账户的每个子用户单独统计数据
Data model
数据模型
| Object | Description | Key fields |
|---|---|---|
| Contact | Marketing recipient | email, first_name, last_name, custom_fields, list_ids, created_at |
| List | Collection of contacts | id, name, contact_count |
| Segment | Dynamic contact filter | id, name, query_dsl (AND/OR conditions) |
| Single Send | One-time marketing email | id, name, status, send_at, categories |
| Automation | Trigger-based email sequence | id, status, trigger, steps |
| Template | Reusable email design | id, name, generation (legacy/dynamic), versions |
| Suppression | Suppressed address | email, type (bounce/block/spam_report/unsubscribe), created_at |
| API Key | Authentication credential | api_key_id, name, scopes |
| Subuser | Child account under parent | username, email, ips |
| Teammate | UI user with role-based access | email, scopes, is_admin |
| IP | Sending IP address | ip, pools, warmup, assigned_at |
| IP Pool | Group of sending IPs | name, ips |
| 对象 | 描述 | 关键字段 |
|---|---|---|
| Contact(联系人) | 营销活动收件人 | email, first_name, last_name, custom_fields, list_ids, created_at |
| List(列表) | 联系人集合 | id, name, contact_count |
| Segment(分群) | 动态联系人筛选规则 | id, name, query_dsl(AND/OR条件) |
| Single Send(一次性群发) | 单次营销邮件 | id, name, status, send_at, categories |
| Automation(自动化流程) | 触发式邮件序列 | id, status, trigger, steps |
| Template(模板) | 可复用的邮件设计 | id, name, generation(legacy/dynamic), versions |
| Suppression(抑制记录) | 被抑制的邮箱地址 | email, type(bounce/block/spam_report/unsubscribe), created_at |
| API Key(API密钥) | 认证凭证 | api_key_id, name, scopes |
| Subuser(子用户) | 主账户下的子账户 | username, email, ips |
| Teammate(团队成员) | 带角色权限的UI用户 | email, scopes, is_admin |
| IP(发送IP) | 发件IP地址 | ip, pools, warmup, assigned_at |
| IP Pool(IP池) | 发件IP分组 | name, ips |
API quick reference
API快速参考
- Base URL:
https://api.sendgrid.com/v3/ - Authentication: Bearer token —
Authorization: Bearer <API_KEY> - Rate limits: 600 req/min general; mail/send up to 10,000 req/sec on high-volume plans
- Message size: 20MB maximum (including attachments)
- Personalizations: Up to 1,000 per mail/send request
- Key endpoints:
- — send email
POST /v3/mail/send - — aggregate statistics
GET /v3/stats - — list bounced addresses
GET /v3/suppression/bounces - — list templates
GET /v3/templates - — add/update marketing contacts
PUT /v3/marketing/contacts - — create single send
POST /v3/marketing/singlesends - — validate email address
POST /v3/validations/email
- SDKs: Node.js (,
@sendgrid/mail), Python, PHP, Java, C#, Go, Ruby@sendgrid/client - Docs: docs.sendgrid.com
- 基础URL:
https://api.sendgrid.com/v3/ - 认证方式:Bearer令牌——
Authorization: Bearer <API_KEY> - 频率限制:通用接口600次请求/分钟;高容量套餐的mail/send接口最高支持10000次请求/秒
- 邮件大小:最大20MB(含附件)
- 个性化配置:每次mail/send请求最多支持1000个
- 核心端点:
- —— 发送邮件
POST /v3/mail/send - —— 汇总统计数据
GET /v3/stats - —— 获取硬退信地址列表
GET /v3/suppression/bounces - —— 获取模板列表
GET /v3/templates - —— 添加/更新营销联系人
PUT /v3/marketing/contacts - —— 创建一次性群发
POST /v3/marketing/singlesends - —— 校验邮箱地址
POST /v3/validations/email
- SDK:Node.js(、
@sendgrid/mail)、Python、PHP、Java、C#、Go、Ruby@sendgrid/client - 官方文档:docs.sendgrid.com
Integrations
集成
| Category | Tools |
|---|---|
| CRM | Salesforce (Data Cloud connector) — no other native CRM integrations |
| Automation | Zapier, Make, n8n |
| E-commerce | Shopify (via integrations), WooCommerce (via plugins) |
| Cloud / Infrastructure | Azure, Heroku, Google Cloud (via SMTP or API) |
| Frameworks | Any framework with HTTP or SMTP support (Django, Rails, Express, Laravel, Spring, etc.) |
| Partner ecosystem | 353 total partner integrations in the SendGrid integration directory |
SendGrid is primarily an API-driven platform — most integrations are built via the REST API or SMTP relay rather than pre-built native connectors.
| 分类 | 工具 |
|---|---|
| CRM | Salesforce(Data Cloud连接器)——无其他原生CRM集成 |
| 自动化工具 | Zapier, Make, n8n |
| 电商 | Shopify(通过集成)、WooCommerce(通过插件) |
| 云/基础设施 | Azure, Heroku, Google Cloud(通过SMTP或API) |
| 开发框架 | 任何支持HTTP或SMTP的框架(Django、Rails、Express、Laravel、Spring等) |
| 合作伙伴生态 | SendGrid集成目录中共有353个合作伙伴集成 |
SendGrid是优先API驱动的平台——大多数集成是通过REST API或SMTP中继构建,而非预构建的原生连接器。
Pricing (USD, as of March 2026 — verify current pricing at sendgrid.com)
定价(美元,2026年3月数据——请以sendgrid.com的当前定价为准)
Email API Plans (transactional email):
| Plan | Price | Volume | Key gated features |
|---|---|---|---|
| Free Trial | $0 (60 days) | 100/day | Basic API access, limited features |
| Essentials | From $19.95/mo | 50,000/mo | Ticket support, no dedicated IP |
| Pro | From $89.95/mo | 1,500,000/mo | Dedicated IP, 2,500 email validations/mo, subuser management, webhook |
| Premier | Custom pricing | 2,500,000+/mo | SSO, 5,000+ validations, priority support |
Marketing Campaigns Plans (email marketing):
| Plan | Price | Contacts | Key gated features |
|---|---|---|---|
| Free Trial | $0 (60 days) | 100 contacts | Basic single sends, limited testing |
| Basic | From $15/mo | 5,000 contacts | Drag-and-drop editor, segmentation, A/B testing |
| Advanced | From $60/mo | 100,000 contacts | Dedicated IP, automations, email testing, signup forms |
| Custom | Custom pricing | 100K+ contacts | Custom volume and support |
IMPORTANT: Email API and Marketing Campaigns are separate subscriptions. If you need both transactional and marketing email, you will have two bills.
Email API套餐(事务性邮件):
| 套餐 | 价格 | 发送额度 | 核心专属功能 |
|---|---|---|---|
| 免费试用 | 0美元(60天) | 100封/天 | 基础API访问,有限功能 |
| Essentials | 每月19.95美元起 | 5万封/月 | 工单支持,无专用IP |
| Pro | 每月89.95美元起 | 150万封/月 | 专用IP、每月2500次邮件验证、子用户管理、Webhook |
| Premier | 定制定价 | 250万封/月以上 | SSO、5000次以上验证、优先支持 |
营销活动套餐(邮件营销):
| 套餐 | 价格 | 联系人额度 | 核心专属功能 |
|---|---|---|---|
| 免费试用 | 0美元(60天) | 100个联系人 | 基础一次性群发,有限测试功能 |
| Basic | 每月15美元起 | 5000个联系人 | 拖拽编辑器、用户分群、A/B测试 |
| Advanced | 每月60美元起 | 10万个联系人 | 专用IP、自动化流程、邮件测试、注册表单 |
| Custom | 定制定价 | 10万个联系人以上 | 定制容量和支持 |
重要提示:Email API和营销活动是独立的订阅服务。如果你同时需要发送事务性和营销邮件,会收到两份账单。
Step 4 — Actionable guidance
步骤4:可落地的操作指导
Based on the user's specific question:
-
Sending transactional email via the API:
- Create an API key in Settings > API Keys with "Mail Send" permission
- Authenticate your sending domain in Settings > Sender Authentication (add the CNAME records to your DNS)
- Install the SDK for your language (e.g., for Node.js)
npm install @sendgrid/mail - Set the API key:
sgMail.setApiKey(process.env.SENDGRID_API_KEY) - Compose and send: set ,
to,from,subject/text(orhtml+templateId)dynamicTemplateData - Handle the response — check for 202 Accepted (success) or error codes
- Set up Event Webhooks to track delivery and engagement events
-
Setting up Marketing Campaigns automation:
- Subscribe to a Marketing Campaigns plan (automations require Advanced plan)
- Import or add contacts to a list — use CSV upload, signup forms, or the Contacts API
- Navigate to Automations > Create Automation
- Choose a trigger: welcome series (new contact added to list), date-based, or custom
- Build the email sequence — add email steps with delays between them
- Design each email using the drag-and-drop editor or code editor
- Activate the automation and monitor entry/completion rates in the automation dashboard
-
Configuring domain authentication:
- Go to Settings > Sender Authentication > Authenticate Your Domain
- Select your DNS host and enter your sending domain
- SendGrid generates CNAME records for SPF and DKIM — add these to your DNS provider
- Click Verify in SendGrid — it checks for the DNS records
- Set up branded tracking links (link branding) — add another CNAME for click/open tracking
- If using a dedicated IP, configure reverse DNS to map the IP to your domain
- Set up a DMARC record separately in your DNS (e.g., )
v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com
-
Setting up Event Webhooks:
- Go to Settings > Mail Settings > Event Webhook
- Enter your webhook URL (must be publicly accessible HTTPS endpoint)
- Select the events you want to receive (processed, delivered, open, click, bounce, etc.)
- Enable the webhook
- Implement signature verification on your endpoint using SendGrid's public key
- Process incoming JSON arrays of event objects — each has ,
event,email, and custom argstimestamp - Handle retries — SendGrid retries failed deliveries for up to 24 hours
-
Setting up Inbound Parse:
- Add an MX record for your receiving domain pointing to
mx.sendgrid.net - Go to Settings > Inbound Parse > Add Host & URL
- Enter your receiving domain and the webhook URL to receive parsed email
- Choose raw (MIME) or parsed (structured fields) format
- Implement your webhook endpoint to process the multipart POST data (from, to, subject, body, attachments)
- Test by sending an email to any address at your configured domain
- Add an MX record for your receiving domain pointing to
根据用户的具体问题提供对应指导:
-
通过API发送事务性邮件:
- 在设置>API密钥中创建带有「邮件发送」权限的API密钥
- 在设置>发件人认证中认证你的发件域名(将生成的CNAME记录添加到你的DNS服务商)
- 安装对应语言的SDK(例如Node.js使用)
npm install @sendgrid/mail - 配置API密钥:
sgMail.setApiKey(process.env.SENDGRID_API_KEY) - 编写并发送邮件:设置、
to、from、subject/text(或者html+templateId)dynamicTemplateData - 处理响应——检查是否返回202 Accepted(成功)或错误码
- 配置事件Webhooks追踪投递和用户参与事件
-
设置营销活动自动化流程:
- 订阅营销活动套餐(自动化流程需要Advanced套餐)
- 导入或添加联系人到列表——可使用CSV上传、注册表单或联系人API
- 进入自动化>创建自动化
- 选择触发条件:欢迎系列(新联系人加入列表)、日期触发、自定义触发
- 构建邮件序列——添加邮件步骤,设置步骤之间的延迟时间
- 使用拖拽编辑器或代码编辑器设计每封邮件
- 激活自动化流程,在自动化 dashboard 中监控进入/完成率
-
配置域名认证:
- 进入设置>发件人认证>认证你的域名
- 选择你的DNS服务商,输入你的发件域名
- SendGrid会生成SPF和DKIM对应的CNAME记录——将这些记录添加到你的DNS服务商
- 在SendGrid中点击验证——系统会检查DNS记录是否生效
- 设置品牌追踪链接(链接品牌化)——添加另一个CNAME记录用于点击/打开追踪
- 如果你使用专用IP,配置反向DNS将IP映射到你的域名
- 在你的DNS中单独配置DMARC记录(例如)
v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com
-
配置事件Webhooks:
- 进入设置>邮件设置>事件Webhook
- 输入你的Webhook URL(必须是公开可访问的HTTPS端点)
- 选择你需要接收的事件(已处理、已投递、打开、点击、硬退信等)
- 启用Webhook
- 在你的端点中使用SendGrid的公钥实现签名验证
- 处理传入的事件对象JSON数组——每个对象包含、
event、email和自定义参数timestamp - 处理重试逻辑——SendGrid对投递失败的请求最多重试24小时
-
设置入站解析:
- 为你的收件域名添加MX记录,指向
mx.sendgrid.net - 进入设置>入站解析>添加主机和URL
- 输入你的收件域名和接收解析后邮件的Webhook URL
- 选择原始(MIME)或解析后(结构化字段)格式
- 实现你的Webhook端点,处理multipart POST数据(发件人、收件人、主题、正文、附件)
- 向你配置的域名下的任意地址发送邮件进行测试
- 为你的收件域名添加MX记录,指向
Gotchas
注意事项
Best-effort from research — verify details against current SendGrid documentation.
- Email API and Marketing Campaigns are separate subscriptions with separate billing. Many users expect one plan covers everything. If you need to send both transactional email (order confirmations, password resets) and marketing email (newsletters, promotions), you need two subscriptions. Budget accordingly and understand which features belong to which plan.
- The Free Trial is 60 days only with 100 emails/day — not a permanent free tier. Unlike some competitors, SendGrid's free offering expires. After 60 days you must upgrade to a paid plan or lose sending capability. Plan your evaluation and migration timeline around this limit.
- Dedicated IPs require warmup or you will hit deliverability problems immediately. New dedicated IPs have no sending reputation. If you send high volume on a cold IP, mailbox providers will throttle or reject your email. Use SendGrid's automated warmup (enabled by default) or create a manual warmup schedule ramping from hundreds to your target volume over 4-6 weeks.
- Suppression groups are not enabled by default — without them, unsubscribes are global. If you do not configure suppression groups (also called "unsubscribe groups"), any unsubscribe removes the contact from ALL your email. Set up suppression groups early (e.g., "Marketing", "Product Updates", "Billing Alerts") so recipients can opt out of specific categories without losing all communication.
- Event Webhook payloads are batched and can be delayed — do not rely on them for real-time logic. SendGrid batches webhook events and may deliver them with a delay of seconds to minutes. If you need real-time delivery confirmation, poll the API or use the mail/send response code (202 = accepted for processing). Design your webhook consumers to handle out-of-order and duplicate events idempotently.
基于调研整理的最优参考——请以SendGrid当前官方文档的细节为准。
- **Email API和营销活动是独立的订阅服务,账单分开。**很多用户以为一个套餐就能覆盖所有功能。如果你需要同时发送事务性邮件(订单确认、密码重置)和营销邮件(newsletter、促销活动),需要订阅两个服务。请提前做好预算规划,明确不同功能所属的套餐。
- **免费试用仅60天,每天最多发100封邮件——不是永久免费 tier。**和部分竞品不同,SendGrid的免费服务会过期。60天后你必须升级到付费套餐,否则会失去发送能力。请根据这个限制规划你的评估和迁移 timeline。
- **专用IP需要预热,否则会立即出现投递问题。**新的专用IP没有发件信誉,如果你在冷IP上发送大量邮件,邮箱服务商将会限流或拒收你的邮件。使用SendGrid的自动预热功能(默认开启),或者创建手动预热计划,在4-6周内从几百封逐步提升到你的目标发送量。
- **抑制分组默认不开启——如果没有配置,退订是全局生效的。**如果你没有配置抑制分组(也叫「退订分组」),任何退订操作都会将联系人从你所有邮件列表中移除。请尽早设置抑制分组(例如「营销活动」、「产品更新」、「账单通知」),这样收件人可以选择退订特定分类的邮件,而不会完全收不到你的消息。
- **事件Webhook payload是批量发送的,可能存在延迟——不要依赖它实现实时逻辑。**SendGrid会批量发送Webhook事件,可能存在几秒到几分钟的延迟。如果你需要实时投递确认,请轮询API或者参考mail/send的响应码(202=已接受处理)。请将Webhook消费者设计为支持幂等处理,可应对乱序和重复事件。
Step 5 — Related skills
步骤5:相关技能
- — Email marketing strategy and best practices (platform-agnostic)
/sales-email-marketing - — Cross-platform email deliverability — SPF/DKIM/DMARC, warmup, inbox placement
/sales-deliverability - — Email open and click tracking strategy
/sales-email-tracking - — Connect SendGrid to other tools via Zapier, Make, or API
/sales-integration - — Funnel strategy and conversion optimization
/sales-funnel - — Not sure which skill to use? The router matches any sales objective to the right skill. Install:
/sales-donpx skills add sales-skills/sales --skills sales-do
- ——邮件营销策略和最佳实践(平台无关)
/sales-email-marketing - ——跨平台邮件投递能力——SPF/DKIM/DMARC、IP预热、收件箱 placement
/sales-deliverability - ——邮件打开和点击追踪策略
/sales-email-tracking - ——通过Zapier、Make或API连接SendGrid与其他工具
/sales-integration - ——转化漏斗策略和转化率优化
/sales-funnel - ——不知道该用哪个技能?路由工具会将任何销售目标匹配到合适的技能。安装命令:
/sales-donpx skills add sales-skills/sales --skills sales-do
Examples
示例
Example 1: Setting up transactional email for a SaaS app
示例1:为SaaS应用设置事务性邮件
User says: "I need to send password reset and welcome emails from my Node.js app using SendGrid."
Skill does:
- Walks through creating a restricted API key with only "Mail Send" permission for security
- Guides domain authentication setup — adding CNAME records for SPF/DKIM
- Shows how to install and configure the API key via environment variable
@sendgrid/mail - Creates two Dynamic Templates in the SendGrid UI — one for password reset (with ) and one for welcome (with
{{reset_link}},{{first_name}}){{login_url}} - Provides code examples using with
sgMail.send()andtemplateIddynamicTemplateData - Recommends setting up Event Webhooks to track delivery failures and trigger alerts for bounces Result: User has production-ready transactional email with templates, proper authentication, and delivery monitoring
用户提问:「我需要用SendGrid从我的Node.js应用发送密码重置和欢迎邮件。」
技能处理流程:
- 指导用户创建仅带有「邮件发送」权限的受限API密钥,提升安全性
- 引导完成域名认证设置——添加SPF/DKIM对应的CNAME记录
- 展示如何安装,并通过环境变量配置API密钥
@sendgrid/mail - 指导在SendGrid UI中创建两个动态模板——一个用于密码重置(带变量),一个用于欢迎邮件(带
{{reset_link}}、{{first_name}}变量){{login_url}} - 提供使用结合
sgMail.send()和templateId的代码示例dynamicTemplateData - 建议配置事件Webhooks追踪投递失败,触发硬退信告警 结果:用户获得生产可用的事务性邮件配置,包含模板、合规的认证方式和投递监控能力
Example 2: Migrating marketing email from Mailchimp to SendGrid
示例2:将营销邮件从Mailchimp迁移到SendGrid营销活动
User says: "We're moving our newsletter from Mailchimp to SendGrid Marketing Campaigns. What's the process?"
Skill does:
- Explains the dual-subscription model — Marketing Campaigns is separate from Email API, so they need the right plan (Basic or Advanced)
- Walks through exporting contacts from Mailchimp (CSV) and importing into SendGrid with field mapping
- Warns to only import subscribed contacts — recreate suppression groups in SendGrid before importing
- Guides recreation of email templates using SendGrid's drag-and-drop editor or code editor
- Covers DNS changes — remove Mailchimp's authentication records and add SendGrid's CNAME records for SPF/DKIM
- Recommends a warmup strategy: start with most engaged contacts, gradually expand over 2-4 weeks, especially if using a new dedicated IP (Advanced plan) Result: User has a migration plan covering contacts, templates, DNS, suppressions, and warmup to maintain deliverability
用户提问:「我们要把newsletter从Mailchimp迁移到SendGrid营销活动,流程是什么?」
技能处理流程:
- 解释双订阅模型——营销活动和Email API是独立的,所以他们需要选择对应的套餐(Basic或Advanced)
- 引导从Mailchimp导出联系人(CSV),并通过字段映射导入到SendGrid
- 提醒仅导入已订阅的联系人——导入前先在SendGrid中重建抑制列表
- 指导使用SendGrid的拖拽编辑器或代码编辑器重建邮件模板
- 讲解DNS变更——移除Mailchimp的认证记录,添加SendGrid的SPF/DKIM对应的CNAME记录
- 推荐预热策略:先给最活跃的联系人发送,在2-4周内逐步扩大发送范围,如果使用新的专用IP(Advanced套餐)尤其需要注意 结果:用户获得完整的迁移方案,覆盖联系人、模板、DNS、抑制列表和预热环节,保障投递能力不受影响
Example 3: Setting up Event Webhooks for delivery tracking
示例3:设置事件Webhooks用于投递追踪
User says: "I want to track which emails bounce and get delivered so I can update our CRM."
Skill does:
- Guides Event Webhook configuration — selecting processed, delivered, deferred, bounce, and dropped events
- Walks through implementing a webhook endpoint that receives JSON event batches
- Explains signature verification using SendGrid's public key to secure the endpoint
- Designs the CRM update logic: mark contacts as "delivered" on delivery events, flag as "invalid" on hard bounces, queue for retry on deferrals
- Warns about batched/delayed delivery and duplicate events — recommends idempotent processing using the event as a deduplication key
sg_message_id - Suggests also subscribing to open and click events for engagement tracking in the CRM Result: User has a webhook pipeline that keeps their CRM in sync with SendGrid delivery and engagement events
用户提问:「我想要追踪哪些邮件被退信、哪些成功投递,用来更新我们的CRM。」
技能处理流程:
- 指导事件Webhook配置——选择已处理、已投递、已延迟、硬退信和已丢弃事件
- 引导实现Webhook端点,接收JSON格式的事件批量数据
- 讲解如何使用SendGrid的公钥实现签名验证,保障端点安全
- 设计CRM更新逻辑:投递事件触发时将联系人标记为「已投递」,硬退信时标记为「无效地址」,延迟投递时加入重试队列
- 提醒事件是批量/延迟发送的,可能存在重复事件——建议使用事件的作为去重键实现幂等处理
sg_message_id - 建议同时订阅打开和点击事件,用于CRM中的用户 engagement 追踪 结果:用户获得可运行的Webhook pipeline,可同步SendGrid的投递和用户参与事件到CRM
Troubleshooting
问题排查
Emails going to spam after switching to a dedicated IP
切换到专用IP后邮件进入 spam 文件夹
Symptom: Deliverability drops and emails start landing in spam shortly after upgrading to a Pro or Advanced plan with a dedicated IP
Cause: The dedicated IP is new and has no sending reputation. Mailbox providers (Gmail, Yahoo, Outlook) are cautious about unknown IPs and will throttle or spam-folder email from them.
Solution: Enable automated IP warmup in Settings > IP Addresses (it should be on by default for new IPs). If you turned it off, re-enable it. During warmup, SendGrid splits your traffic between the new dedicated IP and the shared IP pool, gradually shifting volume to the dedicated IP over weeks. Do not send your full volume on a cold IP. If deliverability is already damaged, pause high-volume sends, re-enable warmup, and start with your most engaged recipients. Monitor mailbox-provider stats to see which providers are rejecting. See for a comprehensive warmup guide.
/sales-deliverability症状:升级到带专用IP的Pro或Advanced套餐后,投递能力下降,邮件开始进入spam文件夹
原因:专用IP是新的,没有发件信誉。邮箱服务商(Gmail、Yahoo、Outlook)对未知IP持谨慎态度,会限流或将来自这些IP的邮件放入spam文件夹。
解决方案:在设置>IP地址中启用自动IP预热(新IP默认应该是开启的,如果你关闭了请重新开启)。预热期间,SendGrid会将你的流量拆分到新的专用IP和共享IP池,在几周内逐步将流量切换到专用IP。不要在冷IP上发送全量邮件。如果投递能力已经受损,请暂停高量发送,重新启用预热,先给最活跃的收件人发送。监控邮箱服务商统计数据,查看是哪些服务商在拒收邮件。完整的预热指南可参考。
/sales-deliverabilityEvent Webhook not receiving events
事件Webhook收不到事件
Symptom: You configured an Event Webhook URL but your endpoint is not receiving any event data
Cause: The webhook URL is not publicly accessible, HTTPS certificate is invalid, the endpoint is returning non-2xx status codes, or the webhook is not enabled.
Solution: Verify the webhook is enabled in Settings > Mail Settings > Event Webhook. Ensure your URL is publicly reachable (not localhost or behind a firewall). Check that your HTTPS certificate is valid and not self-signed. Test the endpoint manually with a POST of sample JSON. Check that your endpoint returns 2xx status codes within 3 seconds — SendGrid treats timeouts and errors as failures and will retry, but eventually stops after 24 hours. Use a tool like ngrok for local development testing. Check SendGrid's Event Webhook activity log for delivery attempts and error codes.
症状:你已经配置了事件Webhook URL,但你的端点没有收到任何事件数据
原因:Webhook URL不是公开可访问的、HTTPS证书无效、端点返回非2xx状态码,或者Webhook没有启用。
解决方案:确认设置>邮件设置>事件Webhook中Webhook已启用。确保你的URL是公开可访问的(不是localhost或者在防火墙后面)。检查你的HTTPS证书有效,不是自签名证书。手动发送示例JSON POST请求测试端点。确认你的端点在3秒内返回2xx状态码——SendGrid会将超时和错误视为投递失败并重试,但24小时后会停止重试。本地开发测试可使用ngrok等工具。查看SendGrid的事件Webhook活动日志,查看投递尝试记录和错误码。
Marketing contacts not appearing in segments
营销联系人没有出现在分群中
Symptom: Contacts were imported or added via the API but do not appear in segments or lists as expected
Cause: Contact ingestion in Marketing Campaigns is asynchronous — it can take minutes to hours for contacts to be fully indexed and available in segments. Alternatively, the import may have partially failed due to invalid fields or duplicate handling.
Solution: Check the import status in Marketing > Contacts > Imports for errors or warnings. Allow up to 2 hours for large imports to fully index. Verify that custom field names in the import match the custom fields defined in your SendGrid account (mismatches cause fields to be silently dropped). Check that contacts have the expected field values by searching for a specific contact in the UI. For API-added contacts (), check the response for the and poll for status. If contacts appear in the list but not the segment, review the segment query conditions — ensure the field names and operators match the actual contact data.
PUT /v3/marketing/contactsjob_idGET /v3/marketing/contacts/imports/{id}症状:联系人已经通过导入或API添加,但没有按照预期出现在分群或列表中
原因:营销活动的联系人摄入是异步的——联系人完成全量索引并在分群中可用可能需要几分钟到几小时。也可能是因为字段无效或重复处理逻辑导致导入部分失败。
解决方案:在营销>联系人>导入中查看导入状态,检查是否有错误或警告。大容量导入最多需要2小时完成全量索引。确认导入中的自定义字段名称和你SendGrid账户中定义的自定义字段匹配(不匹配会导致字段被静默丢弃)。在UI中搜索特定联系人,确认联系人的字段值符合预期。通过API添加的联系人(),可检查响应中的,轮询查看状态。如果联系人出现在列表中但没有出现在分群中,请检查分群的查询条件——确认字段名称和运算符和实际的联系人数据匹配。
PUT /v3/marketing/contactsjob_idGET /v3/marketing/contacts/imports/{id}