Caramel SDK
A TypeScript SDK for creating, refining, and deploying Caramel campaigns and templates from your own code — the same operations your team runs by hand in the Caramel app, callable from a script. Zero runtime dependencies, built on native fetch.
Pre-1.0 — not yet on the public npm registry
@caramel/sdk's own README says it plainly: the API surface and the authentication model are still moving. Request access and we'll share the package and current docs directly with your workspace.
Once your workspace has access:
Node.js 18 or later. Default base URL is api.caramelme.com.
npm install @caramel/sdk - Three ways to authenticate:
-
CaramelSDK.fromCredentials({ email, password }) — sign in directly -
new CaramelSDK({ accessToken, refreshToken? }) — reuse an existing session token -
CaramelSDK.fromIngestKey('ck_live_…') — scoped to the customers module only
Sign in, find a business, and generate a campaign draft:
import { CaramelSDK } from '@caramel/sdk';
const caramel = await CaramelSDK.fromCredentials({
email: process.env.CARAMEL_EMAIL!,
password: process.env.CARAMEL_PASSWORD!,
});
const [business] = await caramel.businesses.list();
const draft = await caramel.campaigns.generate({
businessId: business.id,
prompt: 'Win back customers who have not ordered in 60 days. Warm, not pushy.',
});
console.log(draft.id, draft.validationStatus, draft.evaluationScores?.overall); What you can call
Four modules, matched to what's actually implemented and shipped in the package today.
| Module | Methods | Notes |
|---|---|---|
| businesses | list() | List the businesses your credentials can access. |
| campaigns | list()get()generate()refine()deploy()pause()resume()delete()suggest() | Generate, refine, version, schedule, and manage the full lifecycle of a campaign draft. |
| templates | list()deploy() | List the template library and deploy a template as a starting point. |
| customers | identify()identifyBatch()track()purchase()trackBatch()unmap()forget() | Ships in the package. Backend endpoints are not yet live in production — do not build against this module yet. |
What you can build
The SDK doesn't add new capabilities beyond the Caramel app — it adds automation. Here's what that looks like in practice.
Scheduled campaigns from your own triggers
Wire generate_campaign and deploy() into a cron job, data pipeline, or internal tool. Draft a win-back campaign every Monday without opening the Caramel app.
Internal tools for non-marketers
Build a lightweight dashboard or Slack command that calls campaigns.suggest() and campaigns.generate(), so anyone on the team can spin up a draft without learning the Caramel UI.
Template rollout across many workspaces
If you operate more than one Caramel business — agencies, franchises — loop over businesses.list() and push a template with templates.deploy() instead of repeating manual setup per account.
Your own review workflow
Every generate_campaign response includes validationStatus and evaluationScores. Build your own approval queue or Slack notification on top of that instead of relying on the Caramel app's review screen.
Use cases
Realistic ways teams put the SDK to work, built from what the API actually does.
Scheduled win-back campaigns
A growth team wires generate_campaign into a weekly cron job that drafts a win-back campaign for customers inactive 60+ days, then posts the draft to Slack for a human to review and deploy.
Multi-workspace agency tooling
An agency managing a dozen Caramel workspaces builds an internal tool that loops over businesses.list() and generates a monthly campaign draft for each client from one script, instead of logging into each workspace by hand.
CI-gated campaign review
A team adds a step to their own review process that calls refine_campaign against a style guide before a draft is approved for send, catching tone or compliance issues before a human ever sees it.
Template standardization at scale
An operations lead uses templates.deploy() in a script to push an updated seasonal template to every business in their portfolio in one run, instead of repeating the same steps per workspace.
Error handling
Every failure throws a CaramelError with a machine-readable .code:
AUTH_FAILEDUNAUTHORIZEDINSUFFICIENT_CREDITSTIER_UPGRADE_REQUIREDCAMPAIGN_DEPLOYEDVALIDATION_FAILEDNOT_FOUNDSERVER_ERRORNETWORK_ERRORCONFLICTCUSTOMER_SUPPRESSEDRATE_LIMITEDPAYLOAD_TOO_LARGE Questions before you build
Is @caramel/sdk on npm?
Not yet. The package isn't published to the public npm registry. Request access and we'll share the package and current install instructions directly.
Is the SDK stable?
No — it's pre-1.0. The SDK's own README states that the API surface and the authentication model are still moving. Expect breaking changes before a 1.0 release.
Can I use the customers module?
Not in production yet. It ships in the package's code, but its backend endpoints currently return 404. Everything under businesses, campaigns, and templates is live.
What can I build with the SDK that I can't do in the Caramel app?
Nothing new in terms of capability — the SDK calls the same operations available in the app. What it adds is automation: triggering them from your own schedule, pipeline, or internal tool instead of a person clicking through the UI.
Does the SDK support server-side and client-side use?
It's built for server-side use — the credentials and ingest-key flows assume a trusted environment. It ships as both ESM and CommonJS builds with TypeScript types included.
Start with a Caramel workspace
SDK access is granted per workspace. Create yours, then request access and we'll share the package and current docs.
Get started