SendGrid Management

Complete CLI for managing SendGrid email services - send emails, manage templates, contacts, domains, and more.

Quick Reference

Installation

# Option 1: Run with Deno
deno run --allow-all ~/.claude/skills/sendgrid-management/cli/mod.ts [command]

# Option 2: Compile to binary
cd ~/.claude/skills/sendgrid-management/cli && deno task compile
./dist/sendgrid --help

# Option 3: Install globally
deno install --allow-all -n sendgrid ~/.claude/skills/sendgrid-management/cli/mod.ts

Authentication

# Set API key (saves to ~/.config/sendgrid/config.json)
sendgrid auth login --api-key SG.xxx

# Or use environment variable
export SENDGRID_API_KEY="SG.xxx"

# Check auth status
sendgrid auth status

Command Groups

Core Workflows

Workflow 1: Send Transactional Email

# Simple email
sendgrid mail send \
  --to recipient@example.com \
  --from sender@example.com \
  --subject "Welcome!" \
  --html "<h1>Hello</h1><p>Welcome to our service!</p>"

# With dynamic template
sendgrid mail send \
  --to recipient@example.com \
  --from sender@example.com \
  --template-id d-f43daeeaef504760851f727007e0b5d0 \
  --data '{"name": "John", "order_id": "12345"}'

# Multiple recipients
sendgrid mail send \
  --to user1@example.com,user2@example.com \
  --from sender@example.com \
  --subject "Announcement" \
  --text "Important update..."

# Schedule for later
sendgrid mail send \
  --to recipient@example.com \
  --from sender@example.com \
  --subject "Scheduled" \
  --text "This was scheduled" \
  --send-at "2024-12-25T10:00:00Z"

Workflow 2: Manage Templates

# List all templates
sendgrid template list

# Get template details
sendgrid template get <template-id>

# Create template
sendgrid template create --name "Welcome Email" --generation dynamic

# Create/update version
sendgrid template version create <template-id> \
  --name "v1" \
  --subject "Welcome {{name}}!" \
  --html-file welcome.html \
  --active

Workflow 3: Contact Management

# Add single contact
sendgrid contact add \
  --email user@example.com \
  --first-name John \
  --last-name Doe \
  --list-ids abc123,def456

# Import from file
sendgrid contact import --file contacts.csv

# Search contacts
sendgrid contact search --query "email LIKE '%@example.com'"

# Export contacts
sendgrid contact export --list-id abc123 --output contacts.csv

# Get contact count
sendgrid contact count

Workflow 4: List Management

# Create list
sendgrid list create --name "Newsletter Subscribers"

# List all lists
sendgrid list all

# Add contacts to list
sendgrid list add-contacts <list-id> --emails user1@example.com,user2@example.com

# Remove contacts from list
sendgrid list remove-contacts <list-id> --contact-ids id1,id2

# Delete list
sendgrid list delete <list-id>

Workflow 5: Suppression Management

# View bounces
sendgrid suppression bounces [--start-time 2024-01-01] [--end-time 2024-12-31]

# View blocks
sendgrid suppression blocks

# View spam reports
sendgrid suppression spam-reports

# View unsubscribes
sendgrid suppression unsubscribes

# Delete specific bounce
sendgrid suppression delete bounce user@example.com

# Add to global unsubscribe
sendgrid suppression add unsubscribe user@example.com

Workflow 6: Domain Authentication

# List authenticated domains
sendgrid domain list

# Authenticate new domain
sendgrid domain create --domain example.com

# Get DNS records to add
sendgrid domain get <domain-id>

# Validate domain (after adding DNS)
sendgrid domain validate <domain-id>

# Set as default
sendgrid domain set-default <domain-id>

Workflow 7: Sender Verification

# List verified senders
sendgrid sender list

# Create sender identity
sendgrid sender create \
  --from-email noreply@example.com \
  --from-name "My Company" \
  --reply-to support@example.com

# Resend verification
sendgrid sender resend <sender-id>

# Delete sender
sendgrid sender delete <sender-id>

Workflow 8: Statistics

# Global stats (last 7 days)
sendgrid stats global --days 7

# Stats by category
sendgrid stats category --categories transactional,marketing --days 30

# Stats by mailbox provider
sendgrid stats mailbox-providers --days 7

# Stats by browser
sendgrid stats browsers --days 7

# Stats by device
sendgrid stats devices --days 7

Workflow 9: Webhooks

# List webhooks
sendgrid webhook list

# Create webhook
sendgrid webhook create \
  --url https://example.com/webhook \
  --events delivered,opened,clicked,bounced

# Update webhook
sendgrid webhook update <webhook-id> --enabled false

# Test webhook
sendgrid webhook test <webhook-id>

# Delete webhook
sendgrid webhook delete <webhook-id>

Workflow 10: API Keys

# List API keys
sendgrid apikey list

# Create API key
sendgrid apikey create \
  --name "Production API" \
  --scopes mail.send,templates.read

# Create full access key
sendgrid apikey create --name "Admin Key" --full-access

# Update key name
sendgrid apikey update <key-id> --name "New Name"

# Delete key
sendgrid apikey delete <key-id>

JSON Output

All commands support --json for machine-readable output:

sendgrid template list --json | jq '.[].id'
sendgrid stats global --days 7 --json > stats.json

Environment Variables

API Coverage

Common Issues

Resources

• references/api-endpoints.md - Full API endpoint reference
• references/scopes.md - API key scopes reference
• Official Docs: https://www.twilio.com/docs/sendgrid/api-reference