suprsend-template-schema

Use this skill when you want your AI agent to create, modify, or edit a template variant - “build an SMS variant”, “add a French locale”, “create a tenant-specific welcome email” - without making up brand variable keys or missing the per-channel content shape. The skill loads the variant envelope, per-channel content schemas, and Handlebars/JSONNET syntax references into your agent’s context whenever it detects a template task. Every generated variant validates against https://schema.suprsend.com/template/v2/variant_schema.json and is ready to push with the suprsend-cli skill.

Install

npx skills add https://github.com/suprsend/skills --skill suprsend-template-schema

Try it

Paste this into your agent:

Create a SuprSend email template variant for a welcome email
in English. Use the default tenant.

Your agent loads the skill and produces a variant file with the minimum shape:

{
  "$schema": "https://schema.suprsend.com/template/v2/variant_schema.json",
  "channel": "email",
  "id": "default-en",
  "tenant_id": null,
  "locale": "en",
  "conditions": null,
  "content": { /* channel-specific - see channel reference */ }
}

Push it live:

suprsend template push --slug welcome-email --commit=true

Templates live under ./suprsend/templates/ locally and are pushed as a unit - variants are not managed separately. See Template Commands.

How variants work

Every SuprSend template is modeled as a collection of variants. A variant pairs a channel, locale, optional tenant, and optional condition with channel-specific content. Even a simple template with no multi-tenant or multi-language requirements is just one variant - usually tenant_id: null, locale: "en", conditions: null. Adding more locales, more tenants, or conditional content means adding more variants under the same template. The content object inside a variant validates against a channel-specific schema selected by the channel field.

Channels

The variant’s channel field selects which content schema applies.

All 9 channels and their channel values

Channel	`channel` value	Reference
Email	`email`	Email content schema
SMS	`sms`	SMS content schema
WhatsApp	`whatsapp`	WhatsApp content schema
In-app Inbox	`inbox`	Inbox content schema
Slack	`slack`	Slack content schema
Microsoft Teams	`ms_teams`	MS Teams content schema
Android Push	`androidpush`	Android push content schema
iOS Push	`iospush`	iOS push content schema
Web Push	`webpush`	Web push content schema

Brand variables

Templates can reference tenant/brand properties. There are three shapes - the skill teaches your agent which to use for each case.

Reserved $brand.* keys
Custom tenant properties
Per-recipient URLs

These are the only keys valid directly under $brand.. Any other key under $brand. will not resolve and will break preview rendering - put it under $brand.properties. instead.

Variable	Renders
`{{$brand.brand_id}}`	Tenant slug / id
`{{$brand.brand_name}}`	Tenant display name. The key is `brand_name`, not `name`.
`{{$brand.logo}}`	Tenant logo URL
`{{$brand.primary_color}}`	Primary brand color
`{{$brand.secondary_color}}`	Secondary brand color
`{{$brand.tertiary_color}}`	Tertiary brand color
`{{$brand.timezone}}`	Tenant timezone
`{{$brand.embedded_preference_url}}`	Brand-level embedded preference URL
`{{$brand.hosted_preference_domain}}`	Brand-level hosted preference domain
`{{$brand.blocked_channels}}`	List of channels blocked at the brand level
`{{$brand.social_links.<network>}}`	Brand social link. Built-in `<network>` keys: `x`, `twitter`, `facebook`, `instagram`, `linkedin`, `youtube`, `tiktok`, `discord`, `telegram`, `medium`, `website`

Any property the customer adds on the tenant object that is not in the reserved list is a custom property, and the correct shape is {{$brand.properties.<key>}}. Common examples:

{{$brand.properties.address}}
{{$brand.properties.unsubscribe_url}}
{{$brand.properties.support_url}}
{{$brand.properties.support_email}}

If you don’t recognise the key from the reserved list, default to $brand.properties.<key>.

These are generated per recipient at run-time. They are top-level, not nested under $brand:

{{$embedded_preference_url}}
{{$hosted_preference_url}}

Do not write {{$brand.$hosted_preference_url}} or {{$brand.embedded_preference_url}} when you mean the per-recipient URL - those are different variables (the $brand.embedded_preference_url form refers to the brand-level config, not the recipient-specific URL).

Common anti-patterns

These are the mistakes the skill is built to prevent.

Wrong	Correct
`{{$brand.name}}`	`{{$brand.brand_name}}`
`{{$brand.support_url}}`	`{{$brand.properties.support_url}}`
`{{$brand.unsubscribe_url}}`	`{{$brand.properties.unsubscribe_url}}`
`{{$brand.address}}`	`{{$brand.properties.address}}`
`{{$brand.$hosted_preference_url}}`	`{{$hosted_preference_url}}` (per-recipient) or `{{$brand.hosted_preference_domain}}` (brand config) - pick based on intent

These anti-patterns silently break preview rendering rather than throwing an obvious error. The skill catches them at generation time so you don’t ship a template that looks fine in JSON but renders blank values at send time.

What you can build

A few real things people generate with this skill:

Welcome email in English - single variant, default tenant, default locale.
French locale variant - add a locale: "fr" variant to an existing template.
Tenant-specific welcome email - one variant per tenant, sharing the same template slug.
Multi-channel template - email + SMS + push variants for the same notification.
Slack message with JSONNET body_block - dynamic block construction.

Templating syntax

The skill carries both supported templating syntaxes:

Syntax	When it’s used
Handlebars	Default for every channel. Variables, conditionals, comparisons, date/array helpers. Reference.
JSONNET	Alternative for Slack `body_block` and MS Teams `body_card` when `templating_language: "jsonnet"`. Reference.

Multi-variant patterns

Pattern	Reference
Different content per tenant/brand	Multi-tenant Variants
Translation keys vs. per-locale variants	Multi-lingual Variants

suprsend-workflow-schema - workflow delivery nodes (send_email, send_multi_channel, etc.) reference variants by template slug. Use it for the workflow shape that wraps these variants.
suprsend-cli - suprsend template push / pull / commit / get / list move variant JSON between your editor and a SuprSend workspace.

Learn more

Template Schema Guide

The full variant envelope, selection rules, and complete examples on GitHub.

Templates in SuprSend

How templates work end-to-end in SuprSend.

suprsend-workflow-schema skill

Generate the workflow JSON that delivers these variants.

Agent Skills Overview

All available skills.

Build with AI

MCP

Agent Skills

Agent SDK

Install

Try it

How variants work

Channels

Brand variables

Common anti-patterns

What you can build

Templating syntax

Multi-variant patterns

Learn more

Template Schema Guide

Templates in SuprSend

suprsend-workflow-schema skill

Agent Skills Overview

​Install

​Try it

​How variants work

​Channels

​Brand variables

​Common anti-patterns

​What you can build

​Templating syntax

​Multi-variant patterns

​Related skills

​Learn more

Template Schema Guide

Templates in SuprSend

suprsend-workflow-schema skill

Agent Skills Overview

Install

Try it

How variants work

Channels

Brand variables

Common anti-patterns

What you can build

Templating syntax

Multi-variant patterns

Related skills

Learn more