Gallery
The hosted template gallery: browse templates and copy them into your workspace, and share your own for review. Public on the server that hosts it; other servers read it from ONESEND_GALLERY_URL and fall back to the bundled starter templates.
Where this server reads the gallery from, and whether this workspace can share templates
GET /v1/gallery/status
mode: hosted (this server hosts the gallery), remote (it reads ONESEND_GALLERY_URL), bundled (only the bundled starter templates: no hosted gallery is configured) or off (ONESEND_GALLERY=off). submit.via: hosted (share from this server), cloud_link (through the cloud account this app is linked to), api_key (through ONESEND_GALLERY_API_KEY), or null with the reason.
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"mode": "hosted" | "remote" | "bundled" | "off",
"url": string or null,
"submit": {
"available": boolean,
"via": "hosted" | "cloud_link" | "api_key" | null,
"reason": "off" | "not_configured" | "not_linked" | "viewer" | null,
"cloudUrl": 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)
This workspace's gallery submissions
GET /v1/gallery/submissions
Every template this workspace shared to the gallery, with its review status. On servers that are not linked to a cloud account the list is empty.
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"data": [{
"id": string,
"slug": string,
"name": string,
"description": string,
"category": string,
"tags": [string],
"status": "pending" | "published" | "rejected" | "unlisted",
"reason": string or null,
"version": number,
"sourceTemplateId": string or null,
"updateOf": string or null,
"createdAt": string,
"updatedAt": string,
"reviewedAt": string or null,
"sampleChanged": [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)
Share a template to the gallery
POST /v1/gallery/submissions
Submits a template for review. Pass templateId, or the template itself (document, subject, sample). A moderator approves or rejects it, and the submitter is emailed the decision. Personal data in the sample data is replaced with placeholders; documents with scripts, tracking pixels or remote code are refused (gallery_content_refused), and so are documents over the size limits (gallery_too_large). A template has at most one pending submission (409 submission_pending); submitting a published template again proposes an update. On the hosting server a signed-in member or a full-access API key of the workspace can submit; other servers forward the submission with the cloud account they are linked to, or ONESEND_GALLERY_API_KEY (403 gallery_submit_unavailable without either). Rate limited (429).
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
templateId | string | A template of this workspace (id or slug). The document, subject and sample data are taken from its current version. |
namerequired | string | |
descriptionrequired | string | |
categoryrequired | "welcome" | "auth" | "receipt" | "notification" | "newsletter" | "announcement" | "onboarding" | "billing" | "event" | "feedback" | … | |
style | "editorial" | "luxe" | "brutalist" | "playful" | "corporate" | "minimal" | "retro" | null | |
tags | array of string | Default []. At most 8 items. |
authorName | string or null | Shown as the author. Default: your name. |
consentrequired | true | The submitter confirms the design is their own work and agrees that it is published under the MIT license. |
type | "transactional" | "broadcast" | |
subject | string | |
preheader | string or null | |
document | object | |
sample | object | |
sourceTemplateId | string or null | The template the submission was made from, on the server that forwards it. |
Responses
{
"id": string,
"slug": string,
"name": string,
"description": string,
"category": string,
"tags": [string],
"status": "pending" | "published" | "rejected" | "unlisted",
"reason": string or null,
"version": number,
"sourceTemplateId": string or null,
"updateOf": string or null,
"createdAt": string,
"updatedAt": string,
"reviewedAt": string or null,
"sampleChanged": [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)
Browse the template gallery
GET /v1/gallery
Published templates you can copy into your workspace. On the server that hosts the gallery this endpoint is public (no credentials, any origin). On other servers it needs an API key or session with read access, and reads the hosted gallery (ONESEND_GALLERY_URL) or, when that cannot be reached, the bundled starter templates. Responses carry an ETag (send If-None-Match for a 304) and Cache-Control.
Authentication: None.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
q | query | string | Free text: name, description, category, style and tags. |
category | query | string | |
style | query | string | |
sort | query | "popular" | "new" | popular (featured first, then most used) or new (most recently published). Default: popular. |
cursor | query | string | nextCursor of the previous page. |
limit | query | integer | Page size (default 50, at most 100). 1 to 100. |
preview | query | boolean or null | Include rendered HTML (previewHtml). |
Responses
{
"data": [{
"id": string,
"slug": string,
"name": string,
"description": string,
"category": string,
"style": string,
"author": string,
"tags": [string],
"license": string,
"type": "transactional" | "broadcast",
"subject": string,
"preheader": string or null,
"featured": boolean,
"version": number,
"views": number,
"uses": number,
"publishedAt": string or null,
"updatedAt": string or null,
"previewUrl": string or null,
"previewHtml": string
}],
"nextCursor": string or null,
"total": number,
"source": "hosted" | "remote" | "bundled"
}Errors: 400, 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.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)
Get a gallery template with its document, sample data and preview
GET /v1/gallery/{slug}
On the server that hosts the gallery this endpoint is public (no credentials, any origin). On other servers it needs an API key or session with read access, and reads the hosted gallery (ONESEND_GALLERY_URL) or, when that cannot be reached, the bundled starter templates. Responses carry an ETag and Cache-Control.
Authentication: None.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
slugrequired | path | string |
Responses
{
"id": string,
"slug": string,
"name": string,
"description": string,
"category": string,
"style": string,
"author": string,
"tags": [string],
"license": string,
"type": "transactional" | "broadcast",
"subject": string,
"preheader": string or null,
"featured": boolean,
"version": number,
"views": number,
"uses": number,
"publishedAt": string or null,
"updatedAt": string or null,
"previewUrl": string or null,
"previewHtml": string,
"document": object,
"sample": object,
"source": "hosted" | "remote" | "bundled"
}Errors: 400, 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.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)
Preview a gallery template
GET /v1/gallery/{slug}/preview.html
The template rendered with its sample data, as an HTML page (sandboxed: no scripts, no forms). On the server that hosts the gallery this endpoint is public (no credentials, any origin). On other servers it needs an API key or session with read access, and reads the hosted gallery (ONESEND_GALLERY_URL) or, when that cannot be reached, the bundled starter templates.
Authentication: None.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
slugrequired | path | string |
Responses
Errors: 400, 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.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)
Count a use of a gallery template
POST /v1/gallery/{slug}/use
Called by servers that copied the template into a workspace (POST /v1/gallery/{slug}/clone does it for you). Public on the server that hosts the gallery; send no body. Rate limited per client (429 rate_limited). 404 gallery_not_hosted on other servers.
Authentication: None.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
slugrequired | path | string |
Responses
{
"ok": true,
"uses": number
}Errors: 400, 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.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)
Copy a gallery template into your workspace
POST /v1/gallery/{slug}/clone
Creates a published template from the gallery entry (its document, subject and sample data) and counts a use.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
slugrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
name | string | |
slug | 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, 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)