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.
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 bynpm run cf:gallery). Offline and self-hosted installs always have a gallery, and the dashboard says when it shows the starters. - While
ONESEND_GALLERY_URLis still a placeholder domain (example.comand 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_KEYto 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.