Templates

A template is reusable message content. It targets one channel, carries a subject and body, and is referenced by journeys. Templates decide what gets sent; journeys decide when and to whom.

Plan Deploying library templates requires Growth or above. Browsing the library is available on all plans.

Two template surfaces

Surface	What it is	How to access
Template library	Caramel’s curated catalog of pre-built campaigns across 16+ industries.	`list_template_library`
Deployed templates	The templates currently active in your business — library entries you’ve deployed plus any custom templates created in the dashboard.	`caramel.v1.template.list`

Use list_template_library to browse and pick. Use caramel.v1.template.list to reference templates in your own code (for example, to confirm a template is deployed before linking to it).

The template object

{
  "id":          "tpl_01h7m9k0aabcdefghj1234567",
  "business_id": "bus_01h7m9k0aabcdefghj1234567",
  "name":        "Welcome — Day 0",
  "channel":     "email",
  "subject":     "Welcome to BrewClub, {{first_name}}",
  "from":        "welcome@mail.brewmaster.cafe",
  "reply_to":    "hi@brewmaster.cafe",
  "body":        "<html>…</html>",
  "locale":      "fr",
  "tags":        ["welcome", "onboarding"],
  "deployed":    true,
  "created_at":  "2026-04-15T10:11:22Z",
  "updated_at":  "2026-05-22T08:14:55Z"
}

Field	Description
`channel`	One of `email`, `sms`, `whatsapp`, `push`, `telegram`.
`subject`	Present for email, push, and Telegram. Absent for SMS.
`from`	Sender address. For email, must be on a verified sender domain. For SMS, a registered sender number.
`body`	HTML for email; plain text for SMS; structured JSON for WhatsApp.
`deployed`	`true` once active in your workspace.

Channel availability

Channel	Plan required	Notes
Email	Starter	Default channel. Most library entries are email.
Push	Starter	Web and mobile push, when the contact’s app supports it.
SMS	Growth	Requires a verified sender phone number.
WhatsApp	Growth	Requires Meta tech-provider approval at the business level.
Telegram	Business	Requires a Telegram bot configured in the dashboard.

A template targets a single channel. To send the same message on 2 channels, create 2 templates.

Browse the template library

curl -X POST https://app.caramelme.com/api/functions/caramel-mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method":  "tools/call",
    "id":      1,
    "params": {
      "name": "list_template_library",
      "arguments": {
        "business_id": "bus_01h7m9k0aabcdefghj1234567",
        "type":        "journey",
        "limit":       20
      }
    }
  }'

The type filter selects:

Value	Returns
`journey`	A full automated campaign: an entry segment, a sequence of templates, and timing. The most common pick.
`template`	Message content only. Drop into an existing journey.
`segment`	An audience definition only. Useful when you have your own content but want a proven segment.

The library is industry-aware. A restaurant business sees restaurant-specific entries; a fitness studio sees fitness-specific ones. The industry field on the business drives this filtering automatically — no additional parameter needed.

Deploy a library entry

curl -X POST https://app.caramelme.com/api/functions/caramel-mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method":  "tools/call",
    "id":      1,
    "params": {
      "name": "deploy_template",
      "arguments": {
        "business_id": "bus_01h7m9k0aabcdefghj1234567",
        "template_id": "lib_restaurant_welcome_v3"
      }
    }
  }'

Deployment is atomic and provisions dependencies in order:

Segments — the entry segment and any audience definitions the journey references are created in the business’s workspace.
Templates — each message template in the sequence is created.
Journey — the journey node graph is created, referencing the segments and templates above.

If any step fails, the whole deployment rolls back. Your workspace never ends up with a half-provisioned journey.

Once deployed, the journey appears in list_campaigns with status: "deployed" and all its templates appear in caramel.v1.template.list.

Important A library deploy goes straight to deployed — no pending_review step. Library content is pre-vetted by Caramel.

List your deployed templates

curl -X POST https://gateway.caramelme.com/v1/templates/list \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"businessId":"bus_01h7m9k0aabcdefghj1234567"}'

const res = await fetch('https://gateway.caramelme.com/v1/templates/list', {
  method:  'POST',
  headers: { 'Authorization': `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ businessId: BUSINESS_ID }),
});
const { templates } = await res.json();

import httpx
res = httpx.post(
    'https://gateway.caramelme.com/v1/templates/list',
    headers={'Authorization': f'Bearer {TOKEN}'},
    json={'businessId': BUSINESS_ID},
)
templates = res.json()['templates']

Returns your active template catalog — templates currently available for use in journeys.

Personalization

Templates support handlebars-style placeholders for contact attributes:

Hi {{first_name}},

Your favorite drink is {{favorite_drink}}. Want 10% off your next one?

At send time, Caramel resolves placeholders against the recipient contact. Missing placeholders render as empty strings — not the literal {{first_name}}.

Supported placeholders include every standard contact field (first_name, last_name, email, locale) and any trait attached to the contact by a form submission or integration.

Internationalization

A template can have locale variants. The variant chosen at send time is the recipient’s locale, falling back to the business’s default locale, then to English.

{
  "subject":      "Welcome to BrewClub",
  "subject_i18n": {
    "es": "Bienvenido a BrewClub",
    "fr": "Bienvenue chez BrewClub",
    "de": "Willkommen bei BrewClub",
    "it": "Benvenuto su BrewClub"
  }
}

Library templates ship with English, Spanish, French, German, and Italian variants.

Compliance footers

Caramel automatically appends the required compliance footer (sender address, unsubscribe link) to every email at send time. Do not add your own unsubscribe link — duplicate unsubscribes confuse contacts and risk delivery reputation.

For SMS and WhatsApp, the “STOP to unsubscribe” footer is handled per-channel per the relevant compliance rules.

Template creation

Templates are created through the dashboard — Omnichannel → Templates → New template. There is no public API for creating templates directly.

The generate_campaign tool produces template content as part of generating a full journey, but standalone single-template creation requires the dashboard.

Templates and journeys

A template does not send by itself. It needs a journey to decide which contacts receive it and when. A single template can be referenced by multiple journeys — editing it updates every journey that uses it. Be careful editing a template referenced by a live journey.

See Campaigns and journeys for the orchestration layer.

Workspace isolation

Deployed templates are per-business. A template deployed to business A is invisible to business B. To use the same library entry across multiple businesses, deploy it to each one separately.

See Businesses for more on multi-business scoping.

Next steps

Campaigns and journeys — how templates are sent
Forms and audience — how contacts enter journey entry segments
Authentication — obtaining a token with the right scopes
Tools reference — list_template_library, deploy_template, caramel.v1.template.list