Templates
Block-based templates with variables, conditional blocks and conditional styling.
List templates
GET /v1/templates
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"data": [{
"id": string,
"object": "template",
"slug": string,
"name": string,
"type": "transactional" | "broadcast",
"category": string or null,
"currentVersion": number,
"publishedVersion": number or null,
"subject": string,
"preheader": string or null,
"sourceKind": "blocks" | "html",
"source": object,
"variablesSchema": object or null,
"sampleData": object or null,
"updatedAt": string
}],
"nextCursor": string or null
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Create a template
POST /v1/templates
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
slug | string | Stable name used in sends (template: "welcome"). Generated from the name when omitted. |
namerequired | string | Display name. |
type | "transactional" | "broadcast" | transactional (data from your app) or broadcast (campaigns: filled from contact fields). Default "transactional". |
category | string | |
subjectrequired | string | Subject line with {{variables}}. |
preheader | string | Preview text. |
sourceKind | "blocks" | "html" | blocks (a template document from the designer) or html. Default "blocks". |
sourcerequired | object | A template document ({ version, theme, blocks }) or { html }. |
variablesSchema | object | |
sampleData | object | Example values for previews and test sends. Never used for real recipients. |
publish | boolean | Make this version the one sends use. |
Responses
{
"id": string,
"object": "template",
"slug": string,
"name": string,
"type": "transactional" | "broadcast",
"category": string or null,
"currentVersion": number,
"publishedVersion": number or null,
"subject": string,
"preheader": string or null,
"sourceKind": "blocks" | "html",
"source": object,
"variablesSchema": object or null,
"sampleData": object or null,
"updatedAt": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Get a template (by id or slug)
GET /v1/templates/{id}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "template",
"slug": string,
"name": string,
"type": "transactional" | "broadcast",
"category": string or null,
"currentVersion": number,
"publishedVersion": number or null,
"subject": string,
"preheader": string or null,
"sourceKind": "blocks" | "html",
"source": object,
"variablesSchema": object or null,
"sampleData": object or null,
"updatedAt": string
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Update a template
PATCH /v1/templates/{id}
Content changes create a new version. Pass publish: true to make it the version used for sending.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
slug | string | Stable name used in sends (template: "welcome"). Generated from the name when omitted. |
name | string | Display name. |
type | "transactional" | "broadcast" | transactional or broadcast. |
category | string | |
subject | string | Subject line with {{variables}}. |
preheader | string | Preview text. |
sourceKind | "blocks" | "html" | blocks (a template document from the designer) or html. |
source | object | A template document ({ version, theme, blocks }) or { html }. |
variablesSchema | object | |
sampleData | object | Example values for previews and test sends. Never used for real recipients. |
publish | boolean | Make this version the one sends use. |
draft | boolean | Autosave: update the current unpublished version in place instead of creating a new version. |
Responses
{
"id": string,
"object": "template",
"slug": string,
"name": string,
"type": "transactional" | "broadcast",
"category": string or null,
"currentVersion": number,
"publishedVersion": number or null,
"subject": string,
"preheader": string or null,
"sourceKind": "blocks" | "html",
"source": object,
"variablesSchema": object or null,
"sampleData": object or null,
"updatedAt": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Delete a template
DELETE /v1/templates/{id}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Render a stored template with variables
POST /v1/templates/{id}/render
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
variables | object | |
version | number |
Responses
{
"subject": string,
"html": string,
"text": string,
"warnings": [string]
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Render an ad-hoc template document (no save)
POST /v1/templates/render
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
subject | string | Default "". |
preheader | string | |
sourceKind | "blocks" | "html" | Default "blocks". |
sourcerequired | object | |
variables | object |
Responses
{
"subject": string,
"html": string,
"text": string,
"warnings": [string]
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
List versions of a template
GET /v1/templates/{id}/versions
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"data": [{
"version": number,
"subject": string,
"published": boolean,
"createdAt": string
}]
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)