Sendgrid Automation

1---
2name: sendgrid-automation
3description: "Automate SendGrid email operations including sending emails, managing contacts/lists, sender identities, templates, and analytics via Rube MCP (Composio). Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# SendGrid Automation via Rube MCP
9 
10Automate SendGrid email delivery workflows including marketing campaigns (Single Sends), contact and list management, sender identity setup, and email analytics through Composio's SendGrid toolkit.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active SendGrid connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `sendgrid`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `sendgrid`
253. If connection is not ACTIVE, follow the returned auth link to complete SendGrid API key authentication
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Create and Send Marketing Campaigns (Single Sends)
31 
32**When to use**: User wants to create and send a marketing email campaign to a contact list or segment.
33 
34**Tool sequence**:
351. `SENDGRID_RETRIEVE_ALL_LISTS` - List available marketing lists to target [Prerequisite]
362. `SENDGRID_CREATE_A_LIST` - Create a new list if needed [Optional]
373. `SENDGRID_ADD_OR_UPDATE_A_CONTACT` - Add contacts to the list [Optional]
384. `SENDGRID_GET_ALL_SENDER_IDENTITIES` - Get verified sender ID [Prerequisite]
395. `SENDGRID_CREATE_SINGLE_SEND` - Create the campaign with content, sender, and recipients [Required]
40 
41**Key parameters for SENDGRID_CREATE_SINGLE_SEND**:
42- `name`: Campaign name (required)
43- `email__config__subject`: Email subject line
44- `email__config__html__content`: HTML body content
45- `email__config__plain__content`: Plain text version
46- `email__config__sender__id`: Verified sender identity ID
47- `email__config__design__id`: Use instead of html_content for pre-built designs
48- `send__to__list__ids`: Array of list UUIDs to send to
49- `send__to__segment__ids`: Array of segment UUIDs
50- `send__to__all`: true to send to all contacts
51- `email__config__suppression__group__id` or `email__config__custom__unsubscribe__url`: One required for compliance
52 
53**Pitfalls**:
54- Setting `send_at` on CREATE does NOT schedule the send; it only prepopulates the UI date; use the Schedule endpoint separately
55- `send_at: "now"` is only valid with the Schedule endpoint, not CREATE
56- Must provide either `suppression_group_id` or `custom_unsubscribe_url` for unsubscribe compliance
57- Sender must be verified before use; check with `SENDGRID_GET_ALL_SENDER_IDENTITIES`
58- Nested params use double-underscore notation (e.g., `email__config__subject`)
59 
60### 2. Manage Contacts and Lists
61 
62**When to use**: User wants to create contact lists, add/update contacts, search for contacts, or remove contacts from lists.
63 
64**Tool sequence**:
651. `SENDGRID_RETRIEVE_ALL_LISTS` - List all marketing lists [Required]
662. `SENDGRID_CREATE_A_LIST` - Create a new contact list [Optional]
673. `SENDGRID_GET_A_LIST_BY_ID` - Get list details and sample contacts [Optional]
684. `SENDGRID_ADD_OR_UPDATE_A_CONTACT` - Upsert contacts with list association [Required]
695. `SENDGRID_GET_CONTACTS_BY_EMAILS` - Look up contacts by email [Optional]
706. `SENDGRID_GET_CONTACTS_BY_IDENTIFIERS` - Look up contacts by email, phone, or external ID [Optional]
717. `SENDGRID_GET_LIST_CONTACT_COUNT` - Verify contact count after operations [Optional]
728. `SENDGRID_REMOVE_CONTACTS_FROM_A_LIST` - Remove contacts from a list without deleting [Optional]
739. `SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS` - Delete an entire list [Optional]
7410. `SENDGRID_IMPORT_CONTACTS` - Bulk import from CSV [Optional]
75 
76**Key parameters for SENDGRID_ADD_OR_UPDATE_A_CONTACT**:
77- `contacts`: Array of contact objects (max 30,000 or 6MB), each with at least one identifier: `email`, `phone_number_id`, `external_id`, or `anonymous_id` (required)
78- `list_ids`: Array of list UUID strings to associate contacts with
79 
80**Pitfalls**:
81- `SENDGRID_ADD_OR_UPDATE_A_CONTACT` is asynchronous; returns 202 with `job_id`; contacts may take 10-30 seconds to appear
82- List IDs are UUIDs (e.g., "ca7a3796-e8a8-4029-9ccb-df8937940562"), not integers
83- List names must be unique; duplicate names cause 400 errors
84- `SENDGRID_ADD_A_SINGLE_RECIPIENT_TO_A_LIST` uses the legacy API; prefer `SENDGRID_ADD_OR_UPDATE_A_CONTACT` with `list_ids`
85- `SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS` is irreversible; require explicit user confirmation
86- Email addresses are automatically lowercased by SendGrid
87 
88### 3. Manage Sender Identities
89 
90**When to use**: User wants to set up or view sender identities (From addresses) for sending emails.
91 
92**Tool sequence**:
931. `SENDGRID_GET_ALL_SENDER_IDENTITIES` - List all existing sender identities [Required]
942. `SENDGRID_CREATE_A_SENDER_IDENTITY` - Create a new sender identity [Optional]
953. `SENDGRID_VIEW_A_SENDER_IDENTITY` - View details for a specific sender [Optional]
964. `SENDGRID_UPDATE_A_SENDER_IDENTITY` - Update sender details [Optional]
975. `SENDGRID_CREATE_VERIFIED_SENDER_REQUEST` - Create and verify a new sender [Optional]
986. `SENDGRID_AUTHENTICATE_A_DOMAIN` - Set up domain authentication for auto-verification [Optional]
99 
100**Key parameters for SENDGRID_CREATE_A_SENDER_IDENTITY**:
101- `from__email`: From email address (required)
102- `from__name`: Display name (required)
103- `reply__to__email`: Reply-to address (required)
104- `nickname`: Internal identifier (required)
105- `address`, `city`, `country`: Physical address for CAN-SPAM compliance (required)
106 
107**Pitfalls**:
108- New senders must be verified before use; if domain is not authenticated, a verification email is sent
109- Up to 100 unique sender identities per account
110- Avoid using domains with strict DMARC policies (gmail.com, yahoo.com) as from addresses
111- `SENDGRID_CREATE_VERIFIED_SENDER_REQUEST` sends a verification email; sender is unusable until verified
112 
113### 4. View Email Statistics and Activity
114 
115**When to use**: User wants to review email delivery stats, bounce rates, open/click metrics, or message activity.
116 
117**Tool sequence**:
1181. `SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS` - Get account-wide delivery metrics [Required]
1192. `SENDGRID_GET_ALL_CATEGORIES` - Discover available categories for filtering [Optional]
1203. `SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES` - Get stats broken down by category [Optional]
1214. `SENDGRID_FILTER_ALL_MESSAGES` - Search email activity feed by recipient, status, or date [Optional]
1225. `SENDGRID_FILTER_MESSAGES_BY_MESSAGE_ID` - Get detailed events for a specific message [Optional]
1236. `SENDGRID_REQUEST_CSV` - Export activity data as CSV for large datasets [Optional]
1247. `SENDGRID_DOWNLOAD_CSV` - Download the exported CSV file [Optional]
125 
126**Key parameters for SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS**:
127- `start_date`: Start date YYYY-MM-DD (required)
128- `end_date`: End date YYYY-MM-DD
129- `aggregated_by`: "day", "week", or "month"
130- `limit` / `offset`: Pagination (default 500)
131 
132**Key parameters for SENDGRID_FILTER_ALL_MESSAGES**:
133- `query`: SQL-like query string, e.g., `status="delivered"`, `to_email="user@example.com"`, date ranges with `BETWEEN TIMESTAMP`
134- `limit`: 1-1000 (default 10)
135 
136**Pitfalls**:
137- `SENDGRID_FILTER_ALL_MESSAGES` requires the "30 Days Additional Email Activity History" paid add-on; returns 403 without it
138- Global statistics are nested under `details[].stats[0].metrics`, not a flat structure
139- Category statistics are only available for the previous 13 months
140- Maximum 10 categories per request in `SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES`
141- CSV export is limited to one request per 12 hours; link expires after 3 days
142 
143### 5. Manage Suppressions
144 
145**When to use**: User wants to check or manage unsubscribe groups for email compliance.
146 
147**Tool sequence**:
1481. `SENDGRID_GET_SUPPRESSION_GROUPS` - List all suppression groups [Required]
1492. `SENDGRID_RETRIEVE_ALL_SUPPRESSION_GROUPS_FOR_AN_EMAIL_ADDRESS` - Check suppression status for a specific email [Optional]
150 
151**Pitfalls**:
152- Suppressed addresses remain undeliverable even if present on marketing lists
153- Campaign send counts may be lower than list counts due to suppressions
154 
155## Common Patterns
156 
157### ID Resolution
158Always resolve names to IDs before operations:
159- **List name -> list_id**: `SENDGRID_RETRIEVE_ALL_LISTS` and match by name
160- **Sender name -> sender_id**: `SENDGRID_GET_ALL_SENDER_IDENTITIES` and match
161- **Contact email -> contact_id**: `SENDGRID_GET_CONTACTS_BY_EMAILS` with email array
162- **Template name -> template_id**: Use the SendGrid UI or template endpoints
163 
164### Pagination
165- `SENDGRID_RETRIEVE_ALL_LISTS`: Token-based with `page_token` and `page_size` (max 1000)
166- `SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS`: Offset-based with `limit` (max 500) and `offset`
167- Always paginate list retrieval to avoid missing existing lists
168 
169### Async Operations
170Contact operations (`ADD_OR_UPDATE_A_CONTACT`, `IMPORT_CONTACTS`) are asynchronous:
171- Returns 202 with a `job_id`
172- Wait 10-30 seconds before verifying with `GET_CONTACTS_BY_EMAILS`
173- Use `GET_LIST_CONTACT_COUNT` to confirm list growth
174 
175## Known Pitfalls
176 
177### ID Formats
178- Marketing list IDs are UUIDs (e.g., "ca7a3796-e8a8-4029-9ccb-df8937940562")
179- Legacy list IDs are integers; do not mix with Marketing API endpoints
180- Sender identity IDs are integers
181- Template IDs: Dynamic templates start with "d-", legacy templates are UUIDs
182- Contact IDs are UUIDs
183 
184### Rate Limits
185- SendGrid may return HTTP 429; respect `Retry-After` headers
186- CSV export limited to one request per 12 hours
187- Bulk contact upsert max: 30,000 contacts or 6MB per request
188 
189### Parameter Quirks
190- Nested params use double-underscore: `email__config__subject`, `from__email`
191- `send_at` on CREATE_SINGLE_SEND only sets a UI default, does NOT schedule
192- `SENDGRID_ADD_A_SINGLE_RECIPIENT_TO_A_LIST` uses legacy API; `recipient_id` is Base64-encoded lowercase email
193- `SENDGRID_RETRIEVE_ALL_LISTS` and `SENDGRID_GET_ALL_LISTS` both exist; prefer RETRIEVE_ALL_LISTS for Marketing API
194- Contact adds are async (202); always verify after a delay
195 
196### Legacy vs Marketing API
197- Some tools use the legacy Contact Database API (`/v3/contactdb/`) which may return 403 on newer accounts
198- Prefer Marketing API tools: `SENDGRID_ADD_OR_UPDATE_A_CONTACT`, `SENDGRID_RETRIEVE_ALL_LISTS`, `SENDGRID_CREATE_SINGLE_SEND`
199 
200## Quick Reference
201 
202| Task | Tool Slug | Key Params |
203|------|-----------|------------|
204| List marketing lists | `SENDGRID_RETRIEVE_ALL_LISTS` | `page_size`, `page_token` |
205| Create list | `SENDGRID_CREATE_A_LIST` | `name` |
206| Get list by ID | `SENDGRID_GET_A_LIST_BY_ID` | `id` |
207| Get list count | `SENDGRID_GET_LIST_CONTACT_COUNT` | `id` |
208| Add/update contacts | `SENDGRID_ADD_OR_UPDATE_A_CONTACT` | `contacts`, `list_ids` |
209| Search contacts by email | `SENDGRID_GET_CONTACTS_BY_EMAILS` | `emails` |
210| Search by identifiers | `SENDGRID_GET_CONTACTS_BY_IDENTIFIERS` | `identifier_type`, `identifiers` |
211| Remove from list | `SENDGRID_REMOVE_CONTACTS_FROM_A_LIST` | `id`, `contact_ids` |
212| Delete list | `SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS` | `id`, `delete_contacts` |
213| Import contacts CSV | `SENDGRID_IMPORT_CONTACTS` | field mappings |
214| Create Single Send | `SENDGRID_CREATE_SINGLE_SEND` | `name`, `email__config__*`, `send__to__list__ids` |
215| List sender identities | `SENDGRID_GET_ALL_SENDER_IDENTITIES` | (none) |
216| Create sender | `SENDGRID_CREATE_A_SENDER_IDENTITY` | `from__email`, `from__name`, `address` |
217| Verify sender | `SENDGRID_CREATE_VERIFIED_SENDER_REQUEST` | `from_email`, `nickname`, `address` |
218| Authenticate domain | `SENDGRID_AUTHENTICATE_A_DOMAIN` | `domain` |
219| Global email stats | `SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS` | `start_date`, `aggregated_by` |
220| Category stats | `SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES` | `start_date`, `categories` |
221| Filter email activity | `SENDGRID_FILTER_ALL_MESSAGES` | `query`, `limit` |
222| Message details | `SENDGRID_FILTER_MESSAGES_BY_MESSAGE_ID` | `msg_id` |
223| Export CSV | `SENDGRID_REQUEST_CSV` | `query` |
224| Download CSV | `SENDGRID_DOWNLOAD_CSV` | `download_uuid` |
225| List categories | `SENDGRID_GET_ALL_CATEGORIES` | (none) |
226| Suppression groups | `SENDGRID_GET_SUPPRESSION_GROUPS` | (none) |
227| Get template | `SENDGRID_RETRIEVE_A_SINGLE_TRANSACTIONAL_TEMPLATE` | `template_id` |
228| Duplicate template | `SENDGRID_DUPLICATE_A_TRANSACTIONAL_TEMPLATE` | `template_id`, `name` |
229