Docs / Sending and domains

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

{
  "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.

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):

EndpointWhat it does
GET /v1/gallerySearch (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.htmlThe template rendered with its sample data, sandboxed (no scripts, no forms)
POST /v1/gallery/{slug}/cloneCopy it into your workspace (and count a use)
GET /v1/gallery/statusWhere this server reads the gallery from, and whether this workspace can share templates
GET and POST /v1/gallery/submissionsShare 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.

SettingDefaultWhat it does
ONESEND_GALLERYonoff: only the bundled starter templates; nothing is fetched and nothing can be shared
ONESEND_GALLERY_URLthe hosted gallery's URLThe hosted gallery: {url}/v1/gallery…
ONESEND_GALLERY_API_KEYnoneSecret. A full-access API key of your cloud workspace, used to share templates from this server
ONESEND_GALLERY_TIMEOUT_MS4000Timeout of one request to the hosted gallery
ONESEND_TEMPLATES_DIR<install dir>/templatesThe 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.