Customer.Io Automation

When to use this skill

Use Customer.Io Automation when an AI agent needs a reusable SKILL.md workflow for this job: Automate customer engagement workflows including broadcast triggers, message analytics, segment management, and newsletter tracking through Customer.io via Composio

When not to use it

Skip Customer.Io Automation when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

1. Personal install: create ~/.claude/skills/customerio-automation/SKILL.md (and any bundled scripts) so Claude Code, Claude Desktop, and compatible agents can load it in every project.
2. Project install: commit the same folder at .claude/skills/customerio-automation/ so teammates get the skill with the repo.
3. Restart the agent session after copying files so it re-scans the skills directory, then ask for the task in words that match the skill description.

Full install guide for Claude, Cursor, and Codex

What this skill does

# Customer.io Automation

Automate customer engagement operations -- trigger targeted broadcasts, retrieve delivery metrics, manage audience segments, list newsletters and transactional templates, and inspect trigger execution history -- all orchestrated through the Composio MCP integration.

**Toolkit docs:** [composio.dev/toolkits/customerio](https://composio.dev/toolkits/customerio)

---

## Setup

1. Connect your Customer.io account through the Composio MCP server at `https://rube.app/mcp` 2. The agent will prompt you with an authentication link if no active connection exists 3. Once connected, all `CUSTOMERIO_*` tools become available for execution

---

## Core Workflows

### 1. Trigger a Broadcast Manually fire a pre-configured broadcast to a specific audience with personalization data.

**Tool:** `CUSTOMERIO_TRIGGER_BROADCAST`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `broadcast_id` | integer | Yes | Broadcast ID from Customer.io Triggering Details | | `ids` | array | No | List of customer IDs to target | | `emails` | array | No | List of email addresses to target | | `recipients` | object | No | Complex filter with `and`/`or`/`not`/`segment` operators | | `per_user_data` | array | No | Per-user personalization with `id`/`email` + `data` | | `data` | object | No | Global key-value data for Liquid template personalization | | `data_file_url` | string | No | URL to JSON file with per-line user data | | `email_add_duplicates` | boolean | No | Allow duplicate recipients (default: false) | | `email_ignore_missing` | boolean | No | Skip people without emails (default: false) | | `id_ignore_missing` | boolean | No | Skip people without customer IDs (default: false) |

**Important:** Provide exactly ONE audience option: `recipients`, `ids`, `emails`, `per_user_data`, or `data_file_url`. Rate limit: 1 request per 10 seconds per broadcast.

---

### 2. Retrieve Message Delivery Metrics Fetch paginated delivery metrics for messages with filtering by campaign, type, and time window.

**Tool:** `CUSTOMERIO_GET_MESSAGES`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | No | Message type: `email`, `webhook`, `twilio`, `slack`, `push`, `in_app` | | `metric` | string | No | Metric: `attempted`, `sent`, `delivered`, `opened`, `clicked`, `converted` | | `campaign_id` | integer | No | Filter by campaign ID | | `newsletter_id` | integer | No | Filter by newsletter ID | | `action_id` | integer | No | Filter by action ID | | `start_ts` | integer | No | Start of time window (Unix timestamp) | | `end_ts` | integer | No | End of time window (Unix timestamp) | | `limit` | integer | No | Results per page, 1-1000 (default: 50) | | `start` | string | No | Pagination token from previous response `next` value | | `drafts` | boolean | No | Return draft messages instead of active/sent |

---

### 3. List Audience Segments Retrieve all segments defined in your workspace for audience analysis and broadcast targeting.

**Tool:** `CUSTOMERIO_GET_SEGMENTS`

``` No parameters required -- returns all segments with IDs and metadata. ```

Use segment IDs when targeting broadcasts via the `recipients.segment.id` filter.

---

### 4. List Newsletters Paginate through all newsletter metadata for tracking and analysis.

**Tool:** `CUSTOMERIO_LIST_NEWSLETTERS`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Max per page, 1-100 | | `sort` | string | No | `asc` (chronological) or `desc` (reverse) | | `start` | string | No | Pagination cursor from previous response `next` value |

---

### 5. Discover Transactional Message Templates List all transactional message templates to find IDs for sending via the API.

**Tool:** `CUSTOMERIO_LIST_TRANSACTIONAL_MESSAGES`

``` No parameters required -- returns template IDs and trigger names. ```

---

### 6. Inspect Broadcast Trigger History Review all trigger executions for a broadcast and inspect individual trigger details.

**Tools:** `CUSTOMERIO_GET_TRIGGERS` and `CUSTOMERIO_GET_TRIGGER`

**List all triggers for a broadcast:**

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `broadcast_id` | integer | Yes | The broadcast/campaign ID |

**Get a specific trigger:**

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `broadcast_id` | integer | Yes | The campaign/broadcast ID | | `trigger_id` | string | Yes | Trigger identifier (e.g., `456` or `5-37`) |

---

## Known Pitfalls

| Pitfall | Details | |---------|---------| | **Mutually exclusive audience params** | `CUSTOMERIO_TRIGGER_BROADCAST` requires exactly ONE of `recipients`, `ids`, `emails`, `per_user_data`, or `data_file_url` -- providing multiple causes errors | | **Rate limiting on broadcasts** | Broadcasts are limited to 1 trigger request per 10 seconds per broadcast ID | | **Unix timestamp format** | `start_ts` and `end_ts` in `CUSTOMERIO_GET_MESSAGES` must be Unix timestamps, not ISO strings | | **Pagination tokens** | Messages and newsletters use cursor-based pagination via the `start` parameter -- use the `next` value from previous responses | | **Segment ID resolution** | To target a segment in a broadcast, first fetch segment IDs via `CUSTOMERIO_GET_SEGMENTS`, then reference by ID in `recipients.segment.id` |

---

## Quick Reference

| Tool Slug | Purpose | |-----------|---------| | `CUSTOMERIO_TRIGGER_BROADCAST` | Trigger a broadcast to a defined audience | | `CUSTOMERIO_GET_MESSAGES` | Retrieve message delivery metrics with filters | | `CUSTOMERIO_GET_SEGMENTS` | List all audience segments | | `CUSTOMERIO_GET_SEGMENT_DETAILS` | Get details for a specific segment | | `CUSTOMERIO_LIST_NEWSLETTERS` | Paginate through newsletters | | `CUSTOMERIO_LIST_TRANSACTIONAL_MESSAGES` | List transactional message templates | | `CUSTOMERIO_GET_TRIGGERS` | List all trigger executions for a broadcast | | `CUSTOMERIO_GET_TRIGGER` | Inspect a specific trigger execution |

---

*Powered by [Composio](https://composio.dev)*

Intended uses

• Use Customer.Io Automation when this documented workflow matches the task.