---
title: "Templates and gallery"
description: "Templates are block documents (JSON) that render to table-based email HTML and a plain-text version, in the browser for live preview and on the server at send time. Raw HTML templates are also supported."
url: https://onesend.email/docs/templates/
---
# Templates and gallery

Templates are block documents (JSON) that render to table-based email HTML and a plain-text version, in the browser for live preview and on the server at send time. Raw HTML templates are also supported.

## Anatomy
```json
{
  "version": 1,
  "theme": {
    "canvas": "#F4EFE6", "surface": "#FFFDF8", "surfaceAlt": "#F1EADC",
    "text": "#1B1A17", "textMuted": "#6B655A",
    "primary": "#1B1A17", "onPrimary": "#FFFDF8", "accent": "#E4572E", "border": "#E3DACA",
    "fontHeading": "'Fraunces', Georgia, serif", "fontBody": "'Inter', Helvetica, Arial, sans-serif",
    "fonts": [{ "family": "Fraunces", "href": "https://fonts.googleapis.com/css2?family=Fraunces:wght@600&display=swap" }],
    "radius": 6, "width": 600, "spacing": 8,
    "dark": { "canvas": "#121110", "surface": "#1C1A18", "text": "#F3EEE4" }
  },
  "blocks": [
    { "id": "logo", "type": "logo", "text": "ACME" },
    { "id": "title", "type": "heading", "text": "Receipt #{{ order.id }}", "level": 1 },
    { "id": "status", "type": "callout", "text": "Payment {{ status }}", "tone": "success" },
    { "id": "items", "type": "table", "columns": ["Item", "Price"], "rows": [],
      "rowsFrom": { "each": "order.items", "as": "item", "cells": ["{{ item.name }}", "{{ item.price | currency:\"USD\" }}"] },
      "footer": ["Total", "{{ order.total | currency:\"USD\" }}"] },
    { "id": "retry", "type": "button", "label": "Update card", "href": "{{ billing_url }}",
      "if": { "var": "status", "eq": "failed" } },
    { "id": "foot", "type": "footer", "text": "Acme Inc.", "unsubscribe": false }
  ],
  "styleRules": [
    { "when": { "var": "status", "eq": "failed" },   "theme": { "accent": "#C2410C" }, "blocks": { "status": { "background": "#FEECE2", "color": "#9A3412" } } },
    { "when": { "var": "status", "eq": "refunded" }, "theme": { "accent": "#2563EB" } }
  ]
}
```

### Blocks
`heading` `text` `button` `image` `logo` `divider` `spacer` `columns` `callout` `code` (OTP) `keyValue` `table` `list` `quote` `hero` `social` `footer` `html` `repeat` `section`. Any block can carry `if` (show only when a condition holds), `style`, and `hideOnMobile`.

### Variables
`{{ user.name }}`, with filters such as `{{ name | default:"there" }}` and `{{ amount | currency:"USD" }}`. Missing variables produce render warnings (shown in the designer and by `render`).

### Color-coding by parameter
`styleRules` patch theme tokens and per-block styles when a condition over variables matches. For example, `status=failed` turns the accent and status banner red, `plan=pro` switches to a gold theme. Conditions: `eq`, `neq`, `in`, `gt/gte/lt/lte`, `exists`, `contains`, and `all` / `any` / `not` combinators.

## Designer
The dashboard designer edits the same document: drag blocks, edit inline, switch theme presets, preview desktop/mobile and light/dark, try sample data (including each styleRule branch), and send a test. Versions are kept; sending uses the published version.

## Gallery
The template gallery is a hosted service. Its templates are stored in the database of the cloud that hosts it, reviewed by moderators before they are published, and every OneSend server reads them over HTTP. Nobody contributes templates to the gallery through the source repository.

### Browsing and using templates
In the dashboard, open **Templates → Template gallery**. Search, filter by category and style, sort by popular or newest, preview a template on desktop or mobile, in light or dark mode, and choose **Use this template** to copy it into your workspace's templates. The copy is yours: later changes to the gallery entry do not change it.

The same gallery is in the API and the MCP server (`list_gallery`, `clone_gallery_template`):

| Endpoint | What it does |
|---|---|
| `GET /v1/gallery` | Search (`q`), `category`, `style`, `sort` (`popular` or `new`), cursor paging (`cursor`, `limit` up to 100) |
| `GET /v1/gallery/{slug}` | One template with its document and sample data |
| `GET /v1/gallery/{slug}/preview.html` | The template rendered with its sample data, sandboxed (no scripts, no forms) |
| `POST /v1/gallery/{slug}/clone` | Copy it into your workspace (and count a use) |
| `GET /v1/gallery/status` | Where this server reads the gallery from, and whether this workspace can share templates |
| `GET` and `POST /v1/gallery/submissions` | Share a template; your submissions and their review status |

Responses carry an `ETag` (send `If-None-Match` for a `304`) and `Cache-Control`. On the server that hosts the gallery the reads are public (no credentials, any origin); on every other server they need an API key or session with read access. `source` in a response says where it came from: `hosted`, `remote` or `bundled`.

### Where a server reads the gallery from
| Setting | Default | What it does |
|---|---|---|
| `ONESEND_GALLERY` | `on` | `off`: only the bundled starter templates; nothing is fetched and nothing can be shared |
| `ONESEND_GALLERY_URL` | the hosted gallery's URL | The hosted gallery: `{url}/v1/gallery…` |
| `ONESEND_GALLERY_API_KEY` | none | Secret. A full-access API key of your cloud workspace, used to share templates from this server |
| `ONESEND_GALLERY_TIMEOUT_MS` | `4000` | Timeout of one request to the hosted gallery |
| `ONESEND_TEMPLATES_DIR` | `<install dir>/templates` | The bundled starter templates (Node) |

How the client behaves:
- Requests go through the server's SSRF-guarded fetch, so a gallery on a private or loopback address is refused unless `ONESEND_ALLOW_PRIVATE_NETWORK=true` (for a local test setup).
- Answers are cached in memory for a few minutes and revalidated with their ETag. After a failed request the hosted gallery is not asked again for a minute.
- When the hosted gallery cannot be reached, answers something the server does not understand, or is turned off, the server serves the **bundled starter templates** instead (the `templates/` folder in this repository, bundled into the Cloudflare Worker by `npm run cf:gallery`). Offline and self-hosted installs always have a gallery, and the dashboard says when it shows the starters.
- While `ONESEND_GALLERY_URL` is still a placeholder domain (`example.com` and other reserved names), nothing is fetched and the starters are served.
- Documents from the hosted gallery are checked before they are used, and previews are rendered by this server, never taken from the remote.

### Sharing a template
Open a template's menu (in the templates list, or **⋯** in the designer) and choose **Share to gallery**. Give it a name, a description, a category, an optional style and tags, and confirm that the design is your own work and may be published under the MIT license with your name as the author. The saved version is shared: its design, subject and sample data. The dialog then shows **Submitted, under review**, and **Template gallery → My submissions** lists every submission with its status (under review, published, not accepted with the reason, removed). You are emailed the decision.

- Only templates made in the designer (blocks) can be shared, not HTML templates.
- Personal data in the sample data (email addresses, phone numbers, card numbers, IP addresses, secrets, credentials in links) is replaced with placeholders.
- Templates with scripts, event handlers, frames, forms, stylesheets other than Google Fonts, tracking pixels, hidden images or images over plain http are refused, and so are templates over the size limits (150 KB document, 16 KB sample data, 102 KB rendered).
- A template has at most one submission under review. Sharing a published template again proposes an update; the published version stays until the update is approved.
- Submissions are rate limited per workspace and person.

Who can share:
- **On the cloud:** any signed-in member of the workspace (not viewers), or a full-access API key of the workspace.
- **From the Mac app:** through the cloud account the app is linked to.
- **From a self-hosted server:** set `ONESEND_GALLERY_API_KEY` to a full-access API key of your cloud workspace. Without it, the share dialog explains how to link a cloud account, or to sign in to the cloud and share the template there.

### The bundled starter templates
The `templates/` folder holds the starter templates bundled with every server: the offline fallback above, and the templates the hosted gallery was first loaded with.

```
templates/<id>/
  meta.json       name, description, category, style, author, license, tags, type, subject, preheader
  template.json   the block document
  sample.json     sample variables used for previews and tests
```
Categories: welcome, auth, receipt, notification, newsletter, announcement, onboarding, billing, event, feedback, other.
Styles: editorial, luxe, brutalist, playful, corporate, minimal, retro.

`npm run validate -w @onesend/templates` checks them (schema, meta, missing variables, size), and the repository tests render every one.
