Marketing

Your campaigns, the people they reached, the cars they brought people to, and your message templates.

Your campaigns mail your subscribers and your own book on a schedule. The API reads them with the same numbers the Marketing screen shows, so your systems can report on them and act on what they bring in. Since 1.5.0.

Scope	Grants
`marketing:read`	`GET /api/v1/campaigns`, `GET /api/v1/campaigns/{id}`, its `sends` and `interest`, `GET /api/v1/message-templates`, and subscribing to the marketing events
`marketing:write`	Everything `marketing:read` grants, plus creating, editing, activating, pausing, sending now and deleting campaigns

Neither is a default scope. Both an API key and a Connect Cypress token are accepted.

Campaigns

curl "$BASE/api/v1/campaigns?status=ACTIVE" -H "authorization: Bearer $TOKEN"
curl "$BASE/api/v1/campaigns/clx…" -H "authorization: Bearer $TOKEN"

A campaign is yours when it is in your book or carries one of your promotions. Each one says what it carries (content: a promotion page, a set of cars or a written message), its audience, its schedule, and people:

Field	Meaning
`reached`	Distinct people mail was actually handed to the provider for. Someone listed and never written to is not reached, and mailing a person twice does not make them two
`dispatched`	Messages handed to the provider: a daily campaign mails the same people many times
`delivered`, `opened`, `clicked`	People, not events: a link scanner that clicks every link is not a person
`viewers`	People who opened a car or a promotion page from the campaign, the one figure a scanner cannot fake

Test sends never count. The audience is described by its source: subscribers, crm (with your slice of your own book: tags, lifecycle, companies, contacts), email-list (with how many addresses it holds; the addresses stay in Cypress), or platform, an audience Cypress set up over the platform's businesses, which is described by no organization id.

Sends and interest

curl "$BASE/api/v1/campaigns/clx…/sends" -H "authorization: Bearer $TOKEN"
curl "$BASE/api/v1/campaigns/clx…/interest" -H "authorization: Bearer $TOKEN"

sends lists each dispatch with how many it asked for and, in people, how many were delivered, opened, clicked, viewed a car, bounced, failed or unsubscribed. interest lists your own cars the campaign brought people to, with views, saves, offers and the people behind them. A visitor who went on to another seller's car is not your campaign's to report.

Templates

GET /api/v1/message-templates lists your own templates and the published templates of Cypress's base library (base: true, read-only: clone one in the app to change it). Each carries its published version's subject and document, and whether a draft is waiting.

Create and run a campaign

curl -X POST "$BASE/api/v1/campaigns" \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{
    "name": "Fresh RAV4s",
    "content": "MESSAGE",
    "subject": "New RAV4s this week",
    "body": "Three clean trade-ins just landed.",
    "audience": { "source": "crm", "crm": { "tags": ["vip"] } },
    "schedule": { "frequency": "WEEKLY", "daysOfWeek": [2], "hour": 9 }
  }'

curl -X POST "$BASE/api/v1/campaigns/clx…/activate" -H "authorization: Bearer $TOKEN"
curl -X POST "$BASE/api/v1/campaigns/clx…/pause"    -H "authorization: Bearer $TOKEN"
curl -X POST "$BASE/api/v1/campaigns/clx…/send"     -H "authorization: Bearer $TOKEN"

A new campaign is always a draft; activate starts its schedule, pause stops it, and send mails its audience now without touching the schedule. PATCH /api/v1/campaigns/{id} edits it (the next send moves only when the schedule actually changes), and DELETE removes a draft that never sent: a campaign that has sent is paused, never deleted, because its send record is what unsubscribes were judged against. Every write takes ?dryRun=true and an Idempotency-Key, and is recorded in your audit log with the key or app that made it. The rules are the Marketing screen's own: readiness before activating, suppression on every send, and the same audience resolution.

Who may write. An API key acts as your organization's admin. An app acting for a person needs that person to be a Fleet Manager or an admin. An agent drafts, edits and pauses, but activating and sending are a person's: 403 PEOPLE_ONLY.
Which audiences. Your subscribers, or a crm slice of your own book. A pasted address list is a person's choice in the app (PEOPLE_ONLY: nothing shows those people asked for mail), and the platform's directory is Cypress's (POLICY_DENIED). A campaign Cypress set up over the platform's businesses can be paused through the API, but not activated or sent.
What it carries. A written MESSAGE needs a subject and a body; INVENTORY carries your own cars (vehicleIds); PROMOTION carries one of your promotions (promotionId).

Events

Event	When	Body
`CAMPAIGN.SENT`	A real send went out (a test never counts)	`campaignId`, `sendId`, `trigger`, `asked`, `scheduledFor`; read the results from its `sends` as they come in
`CAMPAIGN.PAUSED`	A person paused it, or it paused itself because every car it carries sold	`campaignId`, `reason` (`MANUAL` or `NO_AVAILABLE_VEHICLES`, which resumes on its own), `pausedAt`
`CAMPAIGN.INTEREST`	A person it mailed viewed, saved or made an offer on one of your cars; once per person, car and kind	`campaignId`, `sendId`, `vehicleId`, `interest`, `contactId`
`CONTACT.UNSUBSCRIBED`	A contact of your own book asked to stop your mail	`contactId`, `email`, `campaignId`, `unsubscribedAt`

They go to the campaign's owner only. No event names a person you do not already hold: contactId appears only when the person is in your own CRM book, and an unsubscribe from someone outside it is not sent at all. Like TASK.*, they are opt-in: only a Cypress-dialect subscription that lists them gets them, and subscribing needs marketing:read.

Campaigns

Sends and interest

Templates

Create and run a campaign

Events

On this page