sales-sendgrid

What this skill does

# SendGrid Platform Help

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.

## Step 1 — Gather context


If `references/learnings.md` exists, read it first for accumulated knowledge.

Ask the user:

1. **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

2. **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

3. **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.

## Step 2 — Route or answer directly

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.

## Step 3 — SendGrid platform reference

**Read `references/platform-guide.md`** for detailed module documentation, pricing, integrations, and data model.

*You no longer need the platform guide details — focus on the user's specific situation.*

## Step 4 — Actionable guidance

Based on the user's specific question:

1. **Sending transactional email via the API**:
   1. Create an API key in Settings > API Keys with "Mail Send" permission
   2. Authenticate your sending domain in Settings > Sender Authentication (add the CNAME records to your DNS)
   3. Install the SDK for your language (e.g., `npm install @sendgrid/mail` for Node.js)
   4. Set the API key: `sgMail.setApiKey(process.env.SENDGRID_API_KEY)`
   5. Compose and send: set `to`, `from`, `subject`, `text`/`html` (or `templateId` + `dynamicTemplateData`)
   6. Handle the response — check for 202 Accepted (success) or error codes
   7. Set up Event Webhooks to track delivery and engagement events

2. **Setting up Marketing Campaigns automation**:
   1. Subscribe to a Marketing Campaigns plan (automations require Advanced plan)
   2. Import or add contacts to a list — use CSV upload, signup forms, or the Contacts API
   3. Navigate to Automations > Create Automation
   4. Choose a trigger: welcome series (new contact added to list), date-based, or custom
   5. Build the email sequence — add email steps with delays between them
   6. Design each email using the drag-and-drop editor or code editor
   7. Activate the automation and monitor entry/completion rates in the automation dashboard

3. **Configuring domain authentication**:
   1. Go to Settings > Sender Authentication > Authenticate Your Domain
   2. Select your DNS host and enter your sending domain
   3. SendGrid generates CNAME records for SPF and DKIM — add these to your DNS provider
   4. Click Verify in SendGrid — it checks for the DNS records
   5. Set up branded tracking links (link branding) — add another CNAME for click/open tracking
   6. If using a dedicated IP, configure reverse DNS to map the IP to your domain
   7. Set up a DMARC record separately in your DNS (e.g., `v=DMARC1; p=quarantine; rua=mailto:[email protected]`)

4. **Setting up Event Webhooks**:
   1. Go to Settings > Mail Settings > Event Webhook
   2. Enter your webhook URL (must be publicly accessible HTTPS endpoint)
   3. Select the events you want to receive (processed, delivered, open, click, bounce, etc.)
   4. Enable the webhook
   5. Implement signature verification on your endpoint using SendGrid's public key
   6. Process incoming JSON arrays of event objects — each has `event`, `email`, `timestamp`, and custom args
   7. Handle retries — SendGrid retries failed deliveries for up to 24 hours

5. **Setting up Inbound Parse**:
   1. Add an MX record for your receiving domain pointing to `mx.sendgrid.net`
   2. Go to Settings > Inbound Parse > Add Host & URL
   3. Enter your receiving domain and the webhook URL to receive parsed email
   4. Choose raw (MIME) or parsed (structured fields) format
   5. Implement your webhook endpoint to process the multipart POST data (from, to, subject, body, attachments)
   6. Test by sending an email to any address at your configured domain

## Gotchas

> Best-effort from research — verify details against current SendGrid documentation.

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **`sg_event_id` changes on retries — do NOT use it for deduplication.** Despite the docs saying `s