Klaviyo Automation Skill for Cursor

Klaviyo Automation via Rube MCP

Automate Klaviyo email and SMS marketing operations through Composio's Klaviyo toolkit via Rube MCP.

Toolkit docs: composio.dev/toolkits/klaviyo

Prerequisites

• Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
• Active Klaviyo connection via RUBE_MANAGE_CONNECTIONS with toolkit klaviyo
• Always call RUBE_SEARCH_TOOLS first to get current tool schemas

Setup

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.

• Verify Rube MCP is available by confirming RUBE_SEARCH_TOOLS responds
• Call RUBE_MANAGE_CONNECTIONS with toolkit klaviyo
• If connection is not ACTIVE, follow the returned auth link to complete Klaviyo authentication
• Confirm connection status shows ACTIVE before running any workflows

Core Workflows

1. List and Filter Campaigns

When to use: User wants to browse, search, or filter marketing campaigns

Tool sequence:

• KLAVIYO_GET_CAMPAIGNS - List campaigns with channel and status filters [Required]

Key parameters:

• channel: Campaign channel - 'email' or 'sms' (required by Klaviyo API)
• filter: Additional filter string (e.g., equals(status,"draft"))
• sort: Sort field with optional - prefix for descending (e.g., '-created_at', 'name')
• page_cursor: Pagination cursor for next page
• include_archived: Include archived campaigns (default: false)

Pitfalls:

• channel is required; omitting it can produce incomplete or unexpected results
• Pagination is mandatory for full coverage; a single call returns only one page (default ~10)
• Follow page_cursor until exhausted to get all campaigns
• Status filtering via filter (e.g., equals(status,"draft")) can return mixed statuses; always validate data[].attributes.status client-side
• Status strings are case-sensitive and can be compound (e.g., 'Cancelled: No Recipients')
• Response shape is nested: response.data.data with status at data[].attributes.status

2. Get Campaign Details

When to use: User wants detailed information about a specific campaign

Tool sequence:

• KLAVIYO_GET_CAMPAIGNS - Find campaign to get its ID [Prerequisite]
• KLAVIYO_GET_CAMPAIGN - Retrieve full campaign details [Required]

Key parameters:

• campaign_id: Campaign ID string (e.g., '01GDDKASAP8TKDDA2GRZDSVP4H')
• include_messages: Include campaign messages in response
• include_tags: Include tags in response

Pitfalls:

• Campaign IDs are alphanumeric strings, not numeric
• include_messages and include_tags add related data to the response via Klaviyo's include mechanism
• Campaign details include audiences, send strategy, tracking options, and scheduling info

3. Inspect Campaign Messages

When to use: User wants to view the email/SMS content of a campaign

Tool sequence:

• KLAVIYO_GET_CAMPAIGN - Find campaign and its message IDs [Prerequisite]
• KLAVIYO_GET_CAMPAIGN_MESSAGE - Get message content details [Required]

Key parameters:

• id: Message ID string
• fields__campaign__message: Sparse fieldset for message attributes (e.g., 'content.subject', 'content.from_email', 'content.body')
• fields__campaign: Sparse fieldset for campaign attributes
• fields__template: Sparse fieldset for template attributes
• include: Related resources to include ('campaign', 'template')

Pitfalls:

• Message IDs are separate from campaign IDs; extract from campaign response
• Sparse fieldset syntax uses dot notation for nested fields: 'content.subject', 'content.from_email'
• Email messages have content fields: subject, preview_text, from_email, from_label, reply_to_email
• SMS messages have content fields: body
• Including 'template' provides the HTML/text content of the email

4. Manage Campaign Tags

When to use: User wants to view tags associated with campaigns for organization

Tool sequence:

• KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS - Get tag IDs for a campaign [Required]

Key parameters:

• id: Campaign ID string

Pitfalls:

• Returns only tag IDs, not tag names/details
• Tag IDs can be used with Klaviyo's tag endpoints for full details
• Rate limit: 3/s burst, 60/m steady (stricter than other endpoints)

5. Monitor Campaign Send Jobs

When to use: User wants to check the status of a campaign send operation

Tool sequence:

• KLAVIYO_GET_CAMPAIGN_SEND_JOB - Check send job status [Required]

Key parameters:

• id: Send job ID

Pitfalls:

• Send job IDs are returned when a campaign send is initiated
• Job statuses indicate whether the send is queued, in progress, complete, or failed
• Rate limit: 10/s burst, 150/m steady

Common Patterns

Campaign Discovery Pattern

1. Call KLAVIYO_GET_CAMPAIGNS with channel='email'
2. Paginate through all results via page_cursor
3. Filter by status client-side for accuracy
4. Extract campaign IDs for detailed inspection

Sparse Fieldset Pattern

Klaviyo supports sparse fieldsets to reduce response size:

fields__campaign__message=['content.subject', 'content.from_email', 'send_times']
fields__campaign=['name', 'status', 'send_time']
fields__template=['name', 'html', 'text']

Pagination

• Klaviyo uses cursor-based pagination
• Check response for page_cursor in the pagination metadata
• Pass cursor as page_cursor in next request
• Default page size is ~10 campaigns
• Continue until no more cursor is returned

Filter Syntax

- equals(status,"draft") - Campaigns in draft status
- equals(name,"Newsletter") - Campaign named "Newsletter"
- greater-than(created_at,"2024-01-01T00:00:00Z") - Created after date

Known Pitfalls

API Version:

• Klaviyo API uses versioned endpoints (e.g., v2024-07-15)
• Response schemas may change between API versions
• Tool responses follow the version configured in the Composio integration

Response Nesting:

• Data is nested: response.data.data[].attributes
• Campaign status at data[].attributes.status
• Mis-parsing the nesting yields empty or incorrect results
• Always navigate through the full path defensively

Rate Limits:

• Burst: 10/s (3/s for tag endpoints)
• Steady: 150/m (60/m for tag endpoints)
• Required scope: campaigns:read
• Implement backoff on 429 responses

Status Values:

• Status strings are case-sensitive
• Compound statuses exist (e.g., 'Cancelled: No Recipients')
• Server-side filtering may return mixed statuses; always validate client-side

Quick Reference

| Task | Tool Slug | Key Params |

|------|-----------|------------|

| List campaigns | KLAVIYO_GET_CAMPAIGNS | channel, filter, sort, page_cursor |

| Get campaign details | KLAVIYO_GET_CAMPAIGN | campaign_id, include_messages, include_tags |

| Get campaign message | KLAVIYO_GET_CAMPAIGN_MESSAGE | id, fields__campaign__message |

| Get campaign tags | KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS | id |

| Get send job status | KLAVIYO_GET_CAMPAIGN_SEND_JOB | id |

*Powered by Composio*