SendGrid

---
name: sendgrid
description: |
  SendGrid API integration with managed OAuth. Send emails, manage contacts, templates, suppressions, and view email statistics.
  Use this skill when users want to send transactional or marketing emails, manage email lists, handle bounces/unsubscribes, or analyze email performance.
  For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
  Requires network access and valid Maton API key.
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: 🧠
    requires:
      env:
        - MATON_API_KEY
---

# SendGrid

Access the SendGrid API with managed OAuth authentication. Send transactional and marketing emails, manage contacts, templates, suppressions, and analyze email performance.

## Quick Start

```bash
# Get user profile
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/sendgrid/v3/user/profile')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

## Base URL

```
https://gateway.maton.ai/sendgrid/{native-api-path}
```

Replace `{native-api-path}` with the actual SendGrid API endpoint path. The gateway proxies requests to `api.sendgrid.com` and automatically injects your OAuth token.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your SendGrid OAuth connections at `https://ctrl.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=sendgrid&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'sendgrid'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Get Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

**Response:**
```json
{
  "connection": {
    "connection_id": "943c6cd5-9a56-4f5b-8adf-ecd4a140049f",
    "status": "ACTIVE",
    "creation_time": "2026-02-11T10:53:41.817938Z",
    "last_updated_time": "2026-02-11T10:54:05.554084Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "sendgrid",
    "metadata": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Specifying Connection

If you have multiple SendGrid connections, specify which one to use with the `Maton-Connection` header:

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/sendgrid/v3/user/profile')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '943c6cd5-9a56-4f5b-8adf-ecd4a140049f')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

All SendGrid API endpoints follow this pattern:

```
/sendgrid/v3/{resource}
```

---

## Mail Send

### Send Email

```bash
POST /sendgrid/v3/mail/send
Content-Type: application/json

{
  "personalizations": [
    {
      "to": [{"email": "[email protected]", "name": "Recipient"}],
      "subject": "Hello from SendGrid"
    }
  ],
  "from": {"email": "[email protected]", "name": "Sender"},
  "content": [
    {
      "type": "text/plain",
      "value": "This is a test email."
    }
  ]
}
```

**With HTML content:**
```bash
POST /sendgrid/v3/mail/send
Content-Type: application/json

{
  "personalizations": [
    {
      "to": [{"email": "[email protected]"}],
      "subject": "HTML Email"
    }
  ],
  "from": {"email": "[email protected]"},
  "content": [
    {
      "type": "text/html",
      "value": "<h1>Hello</h1><p>This is an HTML email.</p>"
    }
  ]
}
```

**With template:**
```bash
POST /sendgrid/v3/mail/send
Content-Type: application/json

{
  "personalizations": [
    {
      "to": [{"email": "[email protected]"}],
      "dynamic_template_data": {
        "first_name": "John",
        "order_id": "12345"
      }
    }
  ],
  "from": {"email": "[email protected]"},
  "template_id": "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

---

## User Profile

### Get User Profile

```bash
GET /sendgrid/v3/user/profile
```

**Response:**
```json
{
  "type": "user",
  "userid": 59796657
}
```

### Get Account Details

```bash
GET /sendgrid/v3/user/account
```

---

## Marketing Contacts

### List Contacts

```bash
GET /sendgrid/v3/marketing/contacts
```

**Response:**
```json
{
  "result": [],
  "contact_count": 0,
  "_metadata": {
    "self": "https://api.sendgrid.com/v3/marketing/contacts"
  }
}
```

### Search Contacts

```bash
POST /sendgrid/v3/marketing/contacts/search
Content-Type: application/json

{
  "query": "email LIKE '%@example.com%'"
}
```

### Add/Update Contacts

```bash
PUT /sendgrid/v3/marketing/contacts
Content-Type: application/json

{
  "contacts": [
    {
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe"
    }
  ]
}
```

**Response:**
```json
{
  "job_id": "2387e363-4104-4225-8960-4a5758492351"
}
```

**Note:** Contact operations are asynchronous. Use the job status endpoint to check progress.

### Get Import Job Status

```bash
GET /sendgrid/v3/marketing/contacts/imports/{job_id}
```

**Response:**
```json
{
  "id": "2387e363-4104-4225-8960-4a5758492351",
  "status": "pending",
  "job_type": "upsert_contacts",
  "results": {
    "requested_count": 1,
    "created_count": 1
  },
  "started_at": "2026-02-11T11:00:14Z"
}
```

### Delete Contacts

```bash
DELETE /sendgrid/v3/marketing/contacts?ids=contact_id_1,contact_id_2
```

### Get Contact by ID

```bash
GET /sendgrid/v3/marketing/contacts/{contact_id}
```

### Get Contact by Email

```bash
POST /sendgrid/v3/marketing/contacts/search/emails
Content-Type: application/json

{
  "emails": ["[email protected]"]
}
```

---

## Marketing Lists

### List All Lists

```bash
GET /sendgrid/v3/marketing/lists
```

**Response:**
```json
{
  "result": [],
  "_metadata": {
    "self": "https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token="
  }
}
```

### Create List

```bash
POST /sendgrid/v3/marketing/lists
Content-Type: application/json

{
  "name": "My Contact List"
}
```

**Response:**
```json
{
  "name": "My Contact List",
  "id": "b050f139-4231-47c8-bf32-94ad76376d3b",
  "contact_count": 0,
  "_metadata": {
    "self": "https://api.sendgrid.com/v3/marketing/lists/b050f139-4231-47c8-bf32-94ad76376d3b"
  }
}
```

### Get List by ID

```bash
GET /sendgrid/v3/marketing/lists/{list_id}
```

### Update List

```bash
PATCH /sendgrid/v3/marketing/lists/{list_id}
Content-Type: applicati