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.
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.
Access the SendGrid API with managed OAuth authentication. Send transactional and marketing emails, manage contacts, templates, suppressions, and analyze email performance.
Quick Start
# 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
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:
# List bounces
GET /sendgrid/v3/suppression/bounces
# Get bounce by email
GET /sendgrid/v3/suppression/bounces/{email}
# Delete bounces
DELETE /sendgrid/v3/suppression/bounces
Content-Type: application/json
{
"emails": ["bounce@example.com"]
}
Blocks
# List blocks
GET /sendgrid/v3/suppression/blocks
# Get block by email
GET /sendgrid/v3/suppression/blocks/{email}
# Delete blocks
DELETE /sendgrid/v3/suppression/blocks
Content-Type: application/json
{
"emails": ["blocked@example.com"]
}
Invalid Emails
# List invalid emails
GET /sendgrid/v3/suppression/invalid_emails
# Delete invalid emails
DELETE /sendgrid/v3/suppression/invalid_emails
Content-Type: application/json
{
"emails": ["invalid@example.com"]
}
Spam Reports
# List spam reports
GET /sendgrid/v3/suppression/spam_reports
# Delete spam reports
DELETE /sendgrid/v3/suppression/spam_reports
Content-Type: application/json
{
"emails": ["spam@example.com"]
}
Global Unsubscribes
# List global unsubscribes
GET /sendgrid/v3/suppression/unsubscribes
# Add to global unsubscribes
POST /sendgrid/v3/asm/suppressions/global
Content-Type: application/json
{
"recipient_emails": ["unsubscribe@example.com"]
}
import os
import requests
# Get email stats
response = requests.get(
'https://gateway.maton.ai/sendgrid/v3/stats',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
params={'start_date': '2026-02-01'}
)
data = response.json()
for day in data:
metrics = day['stats'][0]['metrics']
print(f"{day['date']}: {metrics['delivered']} delivered, {metrics['opens']} opens")
Notes
All requests use JSON content type
Dates are in YYYY-MM-DD format
Template IDs for dynamic templates start with d-
Mail send returns 202 Accepted on success (not 200)
Marketing contact operations are asynchronous - use job status endpoints
Suppression endpoints support date filtering with start_time and end_time (Unix timestamps)
IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments
Error Handling
Status
Meaning
400
Bad request or validation error
401
Invalid or missing Maton API key
403
Insufficient permissions
404
Resource not found
429
Rate limited
500
Internal server error
Troubleshooting: API Key Issues
Check that the MATON_API_KEY environment variable is set:
echo$MATON_API_KEY
Verify the API key is valid by listing connections: