Customer.io API + MCP (2026): three APIs, one official MCP server

Customer.io has no SMTP relay and no single API key — it exposes three separate REST APIs on three hosts with three credential types, and transactional email leaves through the App API at POST /v1/send/email rather than any mail server. That split is the biggest source of integration bugs here. It is also why MCP matters more on this platform than most: Customer.io ships a first-party remote MCP server with OAuth, separate read and write scopes, and 7 tools covering the whole App API rather than a curated handful of actions.

At a glance

MCP integration in 2026

Model Context Protocol is how an assistant such as Claude, ChatGPT or Cursor gets authenticated, structured access to a vendor API instead of guessing at endpoints. Customer.io shipped a first-party server early, and its design — generic API-shaped tools rather than a fixed catalogue of feature verbs — is what gives it full coverage.

Available MCP servers

Two endpoints are worth wiring up, for different risk profiles: the official server for analysis and workspace management, the Zapier endpoint as a narrow write-only ingestion path.

Customer.io API essentials

There is no such thing as “the Customer.io API”. There are three, they do different jobs, and confusing their hosts or credentials is the most common failure mode here. Track ingests people, events and devices. The App API sends transactional messages, triggers broadcasts and manages campaigns, segments and templates. Pipelines (CDP) is a Segment-spec ingestion endpoint. Region is fixed at account creation for every workspace in the account; the dashboard is fly.customer.io in both regions and the EU data centre is in Belgium.

Track v1 is what every official library and third-party CDP connector calls; Customer.io states v2 is not used in any of its own libraries, so /api/v2/entity and /api/v2/batch are a hand-rolled path you opt into for batching. The July 15, 2026 UI rename left endpoint names alone, so /v1/campaigns and /v1/newsletters still work.

Authentication methods

Four distinct credential types are in play. There is no unified key, and a key from one surface returns a bare 401 on another.

Track API — HTTP Basic with Site ID

Username is the Site ID, password the Track API key, both workspace-scoped. It writes people, events, devices and objects and can delete profiles — treat it as a write credential.

App API — Bearer token with scopes

Created in Account Settings under API Credentials, sent as Authorization: Bearer <App API key>. This key sends transactional email, triggers broadcasts, and reads or writes campaigns, segments, collections, exports, snippets and deliveries. Keys are scoped — mint one per integration.

Pipelines (CDP) API — HTTP Basic with a blank password

Username is the source write key, password blank. HTTP clients that drop an empty password field break here. On an unexplained 401, check the raw Authorization header: it must be base64 of writekey: including the trailing colon.

MCP server — OAuth against your login

No API key. OAuth against your Customer.io login, inheriting your role permissions, which is why read, write and delete are separate tools. Connections start read-only; live-data editing and sensitive-attribute reads are explicit toggles added May 26, 2026.

Rate limits

Limits are per API surface, not per account. Customer.io calls them soft — not strictly enforced, but consistently exceeding them may cause throttling or dropped data — and subject to change.

There is no published per-hour email throttle: Customer.io meters monthly email allotment per plan instead, with Essentials including 1 million emails and 5k profiles. The fix for the two limits that actually bite is architectural. For API-triggered broadcasts at 1 per 10 seconds, stop calling per recipient — one trigger carries the whole audience, and per-person timing belongs in an event-triggered automation. For bulk ingestion, move off per-person Track calls onto /api/v2/batch or the Pipelines batch endpoint sized just under 500 KB. Track payload caps are enforced separately, and the 300 unique attributes per person ceiling is the one that surprises B2B teams.

Official SDKs

Customer.io maintains 12 first-party clients in three families. The four server-side clients (Python, Node, Go, Ruby) wrap both the Track API and the App API, transactional send included. The Data Pipelines clients are forks of the Segment libraries and speak only to cdp.customer.io. The five mobile SDKs cover identify and track plus push and in-app.

Notable community SDKs

Community coverage is thin by design. Track and Pipelines are simple enough (Basic auth, JSON POST) that most teams call them with the HTTP client they already have, and because Pipelines follows the Segment spec, any Segment-compatible library works after a host and write-key swap — that is the de facto community SDK layer. For PHP, Java, .NET and Elixir, check last commit date and EU-host support first.

Endpoints reference

The working set. Paths are relative to their own host. Full reference and OpenAPI spec: Customer.io API documentation.

Code examples

Send a transactional email with raw REST

The canonical call. The Bearer header carries the App API key, not the Track API key — swapping them returns 401 with no explanation.

curl --request POST https://api.customer.io/v1/send/email
  --header 'Authorization: Bearer YOUR_APP_API_KEY'
  --header 'Content-Type: application/json'
  --data '{
    "transactional_message_id": "3",
    "to": "person@example.com",
    "identifiers": { "email": "person@example.com" },
    "message_data": { "name": "Person", "order_total": "59.99" }
  }'

# 200 -> { "delivery_id": "...", "queued_at": 1755561600 }
# EU: https://api-eu.customer.io/v1/send/email

Python — transactional send plus ingestion

One package, two clients, two credentials: APIClient is the App API, CustomerIO the Track API.

# pip install customerio
from customerio import APIClient, CustomerIO, Regions, SendEmailRequest

client = APIClient("YOUR_APP_API_KEY", region=Regions.US)  # Regions.EU -> api-eu.customer.io

request = SendEmailRequest(
    to="person@example.com",
    transactional_message_id="3",
    identifiers={"email": "person@example.com"},
    message_data={"name": "person", "order_total": "59.99"},
)

with open("receipt.pdf", "rb") as f:
    request.attach("receipt.pdf", f.read())  # attachments under 2 MB combined

print(client.send_email(request))  # -> {'delivery_id': '...', 'queued_at': ...}

# Ingestion: different API, different credentials
cio = CustomerIO("SITE_ID", "TRACK_API_KEY", region=Regions.US)  # track.customer.io
cio.identify(id="user-123", email="person@example.com", plan="pro")

Connect an assistant to the MCP server

Transport must be http; sse is unsupported. Auth is OAuth in the browser on first connect, so no key lands in the config file.

{
  "mcpServers": {
    "customer-io": {
      "type": "http",
      "url": "https://mcp.customer.io/mcp"
    }
  }
}

// EU workspaces MUST use https://mcp-eu.customer.io/mcp
// Call cio_prime, then cio_schema, before any read or write.

Common gotchas

Deprecations and changelog

• August 18, 2026 — Customer.io AI in Slack: the agent answers @Customer.io mentions. A distinct surface from the MCP server, not a replacement.
• August 6, 2026 — Automation rate limiting by channel, plus a step that holds a profile until the message is actually delivered.
• July 30, 2026 — SMS provider flexibility: Sinch, Infobip and Vonage joined Twilio behind /v1/send/sms.
• July 15, 2026 — UI terminology change (Campaigns to Automations, People to Profiles, Newsletters to One-time sends) with API endpoint names deliberately unchanged.
• May 26, 2026 — MCP connection security toggles: control whether a connection may edit live data and whether it may read sensitive profile attributes.
• March 18, 2026 — Design Studio API endpoints for programmatic creation, update and deletion of emails, components and assets.

No endpoint deprecations landed in this window — the July rename is cosmetic at the API layer. Track the source in the official Customer.io release notes.

Frequently asked questions