Customer.io Platform Help
Help the user with Customer.io platform questions — from behavior-triggered journeys and campaigns through transactional messaging, segmentation, multi-channel delivery (email, SMS, push, in-app, WhatsApp), Data Pipelines, Custom Objects, Ad Audience Sync, and analytics. Customer.io is a customer engagement and marketing automation platform for data-driven, event-based messaging across the entire customer lifecycle. Founded in 2012 by Colin Nederkoorn and John Allison, Customer.io serves 9,000+ brands with $100M+ ARR and differentiates through event-driven automation for product-led companies — while Mailchimp/SendGrid focus on marketing email, Customer.io excels at behavior-triggered messaging (onboarding, activation, retention, re-engagement) with first-party data at the center.
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated knowledge.
Ask the user:
-
What area of Customer.io do you need help with?
- A) Journeys — visual drag-and-drop workflow builder for multi-channel automation
- B) Campaigns — segment-triggered, event-triggered, or date-triggered messaging
- C) Transactional Messages — API-triggered email, push, or SMS (password resets, receipts, etc.)
- D) Segmentation — data-driven (auto-updating) or manual (static) segments
- E) Multi-channel messaging — email, SMS, push notifications, in-app messages, WhatsApp
- F) Data Pipelines — data ingestion API, reverse ETL, Segment integration
- G) Custom Objects — modeling relationships beyond people (accounts, products, subscriptions)
- H) Ad Audience Sync — Google, Facebook, Instagram, YouTube audience sync
- I) Design Studio — collaborative drag-and-drop email editor
- J) A/B & cohort testing — testing content, subject lines, workflow branches, send times
- K) Broadcasts — one-time or scheduled messages to segments
- L) Webhooks — sending/receiving data to any API within journey steps
- M) Analytics — conversion goals, cohort comparison, AI-powered insights
- N) APIs — Track API, App API, Transactional API, Data Pipelines API
- O) Integrations — Salesforce, Segment, Snowflake, BigQuery, Zapier, etc.
- P) Account / Billing — plans, pricing, profile limits
- Q) Something else — describe it
-
What's your role?
- A) Developer / engineer
- B) Product / growth
- C) Marketing / lifecycle
- D) Admin / account owner
- E) Founder / solo operator
- F) Other
-
What are you trying to accomplish? (describe your specific goal or question)
If the user's request already provides most of this context, skip directly to the relevant step. Lead with your best-effort answer using reasonable assumptions (stated explicitly), then ask only the most critical 1-2 clarifying questions at the end — don't gate your response behind gathering complete context.
Note: If the user needs a specialized skill, route them there with a brief explanation of why that skill is a better fit.
Step 2 — Route or answer directly
If the request maps to a specialized skill, route:
- General email marketing strategy / best practices ->
/sales-email-marketing
- Cross-platform email deliverability (not Customer.io-specific) ->
/sales-deliverability
- Email open/click tracking strategy ->
/sales-email-tracking
- Connecting Customer.io to other tools via Zapier or middleware ->
/sales-integration
- Funnel strategy / conversion optimization ->
/sales-funnel
Otherwise, answer directly from platform knowledge using the reference below.
Step 3 — Customer.io platform reference
Read references/platform-guide.md for detailed module documentation, pricing, integrations, and data model.
You no longer need the platform guide details — focus on the user's specific situation.
Step 4 — Actionable guidance
Based on the user's specific question:
-
Event-triggered campaign: ensure your app tracks the trigger event (trial_started, purchase_completed, …) via the Track API or Data Pipelines, then Journeys > Create Journey > "Event triggered" > select the event (optionally filter on event data, e.g. plan = "pro"). Add a delay, then a message action per channel, personalized with Liquid ({{ customer.first_name }}, {{ event.plan_name }}). Add true/false branches for follow-ups, set a conversion goal event with a time window, and test in draft with a test profile before activating.
-
Transactional email via the API: build a Transactional > Email template (Liquid vars like {{ order_number }}, {{ reset_url }}), note its message ID, and get your App API key from Settings > API Credentials — a Bearer token, different from the Track API Site ID/key pair. Send:
POST https://api.customer.io/v1/send/email
Authorization: Bearer YOUR_APP_API_KEY
Content-Type: application/json
{ "transactional_message_id": "YOUR_TEMPLATE_ID", "to": "recipient@example.com",
"identifiers": { "id": "user_123" }, "message_data": { "order_number": "ORD-456" } }
For EU data residency use https://api-eu.customer.io/v1/send/email. Delivery/opens/clicks show in Transactional Messages.
-
Data-driven segments: Segments > Create Segment > Data-driven, combining attribute filters (plan equals "premium"), event filters (performed login ≥3× in 7 days), and engagement filters (opened any email in 30 days) with AND/OR grouping. Preview before saving; use the segment as a journey trigger (people enter on match, exit when they no longer match). Segments re-evaluate in real time as Track API / Data Pipelines data arrives — no manual refresh.
-
Webhook inside a journey: add a "Send Webhook" action at a journey step; set method (GET/POST/PUT/PATCH/DELETE), URL, headers, and a Liquid body ({ "user_id": "{{ customer.id }}", "plan": "{{ customer.plan }}" }) plus auth headers as needed. Use it to update a CRM, ping Slack, or call your own API; branch the journey on the response status (success/failure). Test in draft first.
-
Data Pipelines ingestion: Data Pipelines > Sources > Add Source; pick a source (JS/browser, server SDK for Node/Python/Ruby/Go/Java/PHP, or HTTP API) and copy its . Send data via (create/update a person) and (event). The API is (minimal changes when migrating). For (Snowflake/BigQuery) add a source with sync schedules, add (Amplitude/Mixpanel/webhook) to route data beyond Journeys, and monitor source health for volume/errors/latency.
Gotchas
Best-effort from research — verify details against current Customer.io documentation.
-
Essentials plan starts at $100/mo, which is steep for small senders. Unlike Mailchimp (free tier up to 500 contacts) or SendGrid (free tier for 100 emails/day), Customer.io has no free plan and the entry point is $100/mo for 5,000 profiles. If you are a very early-stage startup or small sender with fewer than a few thousand contacts, evaluate whether Customer.io's event-driven automation justifies the cost versus simpler tools. The $0.009/profile overage also adds up quickly at scale.
-
Only 2 custom object types are available on the Essentials plan. If you need to model more than 2 non-person entities (e.g., accounts, products, subscriptions, orders), you must upgrade to Premium ($1,000/mo annual). Plan your data model carefully before committing to Essentials — if you need accounts and one more object type, you are already at the limit.
-
API-triggered broadcasts are rate-limited to 1 request per 10 seconds. This is significantly slower than the Track API (1000 req/sec fair-use) or Transactional API (100 req/sec). Do not use API-triggered broadcasts for high-frequency or real-time use cases. If you need to send urgent one-time messages to many people quickly, consider using the Transactional API for individual sends or schedule the broadcast in advance rather than triggering it via API at the last moment.
-
In-app messages require Customer.io SDK integration in your application. Unlike email or SMS which work without any client-side code, in-app messages need the Customer.io JavaScript SDK (web) or mobile SDK (iOS/Android/React Native/Flutter) installed and initialized in your app. This means engineering work to integrate the SDK, handle message rendering, and manage the user session. Budget development time for this — it is not a plug-and-play channel.
-
SMS requires a separate Twilio account and incurs separate Twilio charges. Customer.io does not provide SMS infrastructure directly — it uses Twilio under the hood. You must create a Twilio account, purchase a phone number, and connect your Twilio credentials to Customer.io. SMS costs are billed by Twilio (not Customer.io) based on Twilio's per-message pricing. This adds billing complexity and means your total messaging cost is split across two vendors.
- Self-improving: If you discover something not covered here, append it to
references/learnings.md with today's date.
Step 5 — Related skills
/sales-email-marketing — Email marketing strategy and best practices (platform-agnostic)/sales-deliverability — Cross-platform email deliverability — SPF/DKIM/DMARC, warmup, inbox placement/sales-email-tracking — Email open and click tracking strategy/sales-integration — Connect Customer.io to other tools via Zapier, webhooks, or API/sales-funnel — Funnel strategy and conversion optimization/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do
Examples
Example 1: Building an onboarding drip sequence triggered by signup
User says: "I want to send a 5-email onboarding sequence when someone signs up for our SaaS product, with different paths based on whether they complete key activation steps."
Skill does:
- Confirms the user is tracking a
signed_up event (or equivalent) via the Track API or Data Pipelines — if not, guides them through instrumenting the event
- Creates a new journey triggered by the
signed_up event
- Designs a 5-step email sequence with delays: welcome email (immediate), getting started guide (day 1), key feature walkthrough (day 3), activation nudge (day 5), check-in (day 7)
- Adds branching logic after step 3: checks if the person has performed the
activated event — true branch skips the activation nudge and sends a "great job" email instead; false branch continues with the nudge
- Sets
activated as the conversion goal with a 14-day window
- Uses Liquid templating for personalization:
{{ customer.first_name }}, {{ customer.company }}, {{ customer.plan }}
- Tests the journey with a test profile in draft mode before activating
Result: User has a behavior-driven onboarding sequence that adapts based on whether the user activates, with conversion tracking to measure effectiveness
Example 2: Setting up transactional order confirmation emails
User says: "We need to send order confirmation emails with line items immediately after purchase, triggered from our backend API."
Skill does:
- Creates a transactional message template in Customer.io with Liquid templating for order data:
{{ order_number }}, {{ items }} (looped with {% for item in message_data.items %}), {{ total }}
- Guides the user through getting their App API key from Settings > API Credentials
- Shows the API call structure:
POST https://api.customer.io/v1/send/email with transactional_message_id, to, identifiers, and message_data containing the order details
- Recommends including the person's
id in identifiers so the transactional send is associated with their profile for analytics
- Advises setting up a webhook or checking the Transactional Messages dashboard to monitor delivery failures
- Notes: if the user is on EU infrastructure, switch to
api-eu.customer.io
Result: User has production-ready transactional order confirmation emails triggered from their backend with dynamic line-item rendering
Example 3: Syncing a high-value customer segment to Google Ads for suppression
User says: "We want to stop showing acquisition ads to people who are already paying customers. Can Customer.io sync our paying customer segment to Google Ads?"
Skill does:
- Confirms the user has a data-driven segment that identifies paying customers (e.g.,
plan is not "free" AND subscription_status equals "active")
- Walks through setting up Ad Audience Sync: go to Integrations > Ad Audiences > Google Ads
- Connects the Google Ads account via OAuth
- Maps the paying customer segment to a Google Ads customer list
- Explains that the audience syncs automatically as people enter/exit the segment — new paying customers are added and churned customers are removed
- Recommends creating an exclusion audience in Google Ads using this synced list to suppress existing customers from acquisition campaigns
Result: User's acquisition ad spend is optimized by automatically excluding paying customers, with the audience staying current as subscription status changes
Troubleshooting
Events not triggering campaigns or journeys
Symptom: You are tracking events via the Track API or Data Pipelines, but event-triggered campaigns or journeys are not firing for those events.
Cause: The most common cause is that the person does not exist in Customer.io before the event is tracked. The Track API requires that a person is identified (PUT /customers/{id}) before events can be associated with them. Another common cause is a mismatch between the event name in your code and the event name configured as the journey trigger (event names are case-sensitive). Finally, check that the journey is in an active state — draft or paused journeys will not trigger.
Solution: Verify the person exists by checking their profile in Customer.io (People > search by ID or email). Ensure you call identify before track in your integration code. Double-check the event name matches exactly (case-sensitive) between your code and the journey trigger configuration. Confirm the journey status is "Active" in the Journeys list. Use the Activity Log to see if Customer.io received the event at all — if the event does not appear, the issue is in your integration code or API authentication.
SMS messages not sending despite being configured in a journey
Symptom: Email steps in a journey work correctly, but SMS steps are skipped or show errors in the journey analytics.
Cause: SMS in Customer.io requires a connected Twilio account with an active phone number. If Twilio credentials are not configured, expired, or the Twilio account has insufficient funds, SMS steps will fail silently or be skipped. Additionally, the person must have a valid phone number attribute (typically phone or a custom attribute mapped in settings) and must not have unsubscribed from SMS.
Solution: Go to Settings > Workspace Settings > SMS to verify your Twilio Account SID, Auth Token, and phone number are correctly configured. Test the Twilio connection by sending a test SMS. Check the person's profile to confirm they have a valid phone number in the expected attribute field. Verify the person's SMS subscription status is not unsubscribed. Check your Twilio account dashboard for any errors, insufficient balance, or number compliance issues.
Data Pipelines events appearing in the source dashboard but not in person profiles
Symptom: The Data Pipelines source shows events being received (event count is increasing), but when you look at individual person profiles in Customer.io, the events do not appear.
Cause: Data Pipelines requires that an identify call is made for a person before track events are associated with their profile. If you are sending track calls with a userId that has never been identified, the events may be received by the pipeline but not associated with a person profile. Another cause is that the Data Pipelines destination for Customer.io Journeys is not enabled or is misconfigured.
Solution: Verify that you are calling analytics.identify("user_id", { traits }) before or alongside your analytics.track() calls. Check Data Pipelines > Destinations to confirm that Customer.io Journeys is listed as a destination and is enabled. Review the destination's event delivery logs for any errors. If using reverse ETL from a warehouse, verify that the sync mapping includes both identity and event data, and check the sync schedule to ensure it has run recently.
