New Integration: SendGrid

Description

Add SendGrid integration to sync email delivery events, campaigns, and analytics into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/gmail/ - Similar email-based integration
• integrations/slack/ - Messaging and notification patterns
• integrations/linear/ - For reference

Required Files Structure

integrations/sendgrid/
├── src/
│   ├── index.ts          # Main entry, API key spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # SendGrid API utilities
│   ├── account-create.ts # API key setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

SendGrid API Integration

Auth Setup

• Use API Key authentication
• API Key sent in Authorization: Bearer <API_KEY> header
• Base URL: https://api.sendgrid.com/v3/
• All requests must be over HTTPS (HTTP not supported)

Key Endpoints

• POST /v3/mail/send - Send email
• GET /v3/stats - Retrieve email statistics
• GET /v3/messages - Email activity feed
• GET /v3/campaigns - List marketing campaigns
• GET /v3/contactdb/recipients - Contact management
• GET /v3/suppression/bounces - Bounce management
• GET /v3/templates - Email templates
• POST /v3/user/webhooks/event/settings - Configure event webhooks

Events to Track

1. Email Delivery - Sent, delivered, bounced, deferred
2. Engagement - Opened, clicked, unsubscribed
3. Campaigns - Campaign created, sent, completed
4. Suppressions - Bounces, spam reports, unsubscribes
5. Templates - Template created, updated, deleted

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement API key authentication flow in account-create.ts
• Create API utilities in utils.ts for v3 API
• Implement sync logic in schedule.ts for email events and statistics
• Set up webhook handling for real-time delivery events
• Convert SendGrid events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• SendGrid is owned by Twilio; API docs are hosted on Twilio's domain
• SDKs available for 7 languages (Node.js, Python, Ruby, Go, Java, C#, PHP)
• Event webhooks provide real-time delivery and engagement notifications
• Postman collections available for interactive API exploration
• API key must be included in the Authorization header as a Bearer token

Resources

• SendGrid v3 API Reference
• Getting Started with SendGrid API
• SendGrid API Requests
• SendGrid API Responses
• SendGrid Python SDK (GitHub)

Labels

enhancement, integration, new-feature

Start by comparing integrations/gmail/, integrations/slack/, integrations/linear/, and integrations/github/src/index.ts. Trace the existing account setup, scheduling, activity formatting, and webhook patterns before defining the SendGrid integration files listed in the issue. Done means the API-key flow, event and statistics synchronization, webhooks, error handling, documentation, and integrations/README.md entry are complete.