# Not just another marketing API.

The cross-channel platform powering 2–8× revenue per message for enterprise brands — now fully headless. Build agents, services, and custom experiences on top of the same data model the Cordial app uses.

## The headless turn

## Cordial, now built for builders.

Same enterprise-grade platform. New surface area — designed for engineers, services, and agents.

### Every object, exposed

Contacts, audiences, messages, orchestrations, supplements, sculpt blocks, reports — the entire Cordial data model is reachable through one consistent API. The same data your marketing team works with, available to your code.

### The logic comes with the data

A raw database hands code a pile of rows. Cordial hands it the years of marketing logic on top — cross-channel identity resolution, audience definitions, orchestration triggers, and the send history behind 2–8× revenue per message. Your agents inherit the context, not just the schema.

### AI-native by default

A first-class MCP server lets Claude, Cursor, and any MCP-compatible assistant reason about your account out of the box — audiences, performance, and orchestration logic, all account-aware. No exports, no glue, no integration project.

## Give your AI a Cordial account.

Pointing an agent at raw API endpoints isn't enough — it needs the brand, account, and customer context to use them correctly. That's what the MCP server hands over: 56+ tools across 17 domains from one endpoint, so your assistant reasons over the same live account your marketers do — audiences, message performance, orchestration logic, campaign history. Reads today; human-approved writes coming soon.

- ✓Account context — account-aware on every call; the agent always knows which account, scopes, and channels are in play.
- ✓Brand context — semantic search and composite tools like `get_audience_health` speak in your brand's concepts, not raw rows.
- ✓Customer context — identity, profile, and cross-channel history, so the agent reasons about a real person on a real journey.

```json
{
  "mcpServers": {
    "cordial": {
      "type": "http",
      "url": "https://mcp.cordial.io/mcp",
      "auth": "oauth"
    }
  }
}
```

```javascript
// agent.ts — your assistant calls Cordial tools directly
const audiences = await mcp.call("list_audiences", {
  query: "loyalty"
});

const health = await mcp.call("get_audience_health", {
  id: audiences.audiences[0].id,
  period: 30,
});

// "Loyalty tier 3+ has grown 14.2% over the last 30 days,
//  now at 198,455 contacts — see attached trend chart."
```

```shell
# Sign in once — OAuth in your browser
cosdk login

# Find the audience you care about
cosdk audiences list --query "high intent"

# Send a campaign QA preview to your inbox
cosdk messages preview msg_2025_blackfriday --open-raw

# Year-over-year report, piped into your tooling
cosdk analytics overview --start 1y --compare --json | jq '.channels'
```

## From zero to sent in five commands.

One npm install, sign in once, JSON output by default for piping into jq, scripts, and CI. Every concept in your account — audiences, messages, orchestrations, content — in one composable command.

## Direct HTTP, when you need it.

106 endpoints across 24 resources, all over plain HTTPS with HTTP Basic auth. Build in any language — curl, Go, Python, Ruby, Java — no SDK required.

```shell
# Upsert a contact
curl -u "$CORDIAL_API_KEY:" \
  https://api.cordial.io/v2/contacts \
  -H "Content-Type: application/json" \
  -d '{
    "channels": { "email": { "address": "jane@brand.com" } },
    "attributes": { "loyalty_tier": "gold" }
  }'

# Log a custom event — triggers orchestrations, audiences, sends
curl -u "$CORDIAL_API_KEY:" \
  https://api.cordial.io/v2/contactactivities \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@brand.com", "action": "browse",
        "properties": { "product_id": "p_8421" } }'

# Send from an automation template
curl -u "$CORDIAL_API_KEY:" \
  https://api.cordial.io/v2/automationtemplates/welcome/send \
  -H "Content-Type: application/json" \
  -d '{ "to": { "email": "jane@brand.com" } }'
```

## One platform, three ways to build.

MCP for agents, CLI for terminals and scripts, REST API for everything else. Same data model — pick the surface that fits the job.

## Agents are only as good as the context they're given.

Three layers of context that turn a generic LLM into something that actually understands marketing. Stack them, or pick the one you need.

### 01 · Visual context

**SAM MCP**  
The agent sees the pixels, not just the filename. 46 image-aware tools across assets, products, and AI generation.

### 02 · Program context

No Cordial account needed  
**Understand.email MCP**  
What your program is shipping, where it's weak, and what an A+ grade looks like — 7-category audit for the AI inbox era.

### 03 · Opinionated playbooks

**Agentic Cookbook**  
Claude Skills and recipes that bundle the expert craft — prompts, references, and tool-use patterns — for one specific marketing job.

## What teams ship with headless Cordial.

### AI marketing copilots

Wire your assistant into the same audience and message data your team uses every day.

### Automated campaign QA

Render previews across cohorts, diff against past sends, and catch issues before launch.

### Custom marketer UIs

Build internal tools against the REST API — stable v2 contract, JSON-everywhere, your stack of choice.

### Data pipelines

Pipe analytics, audience trends, and message reports into Snowflake, BigQuery, or your own warehouse.

## Start building on headless Cordial.

Install the CLI in 30 seconds. Connect your AI assistant in a config file.