---
title: "Gallery API"
description: "Gallery in the OneSend API: 8 endpoints. The hosted template gallery: browse templates and copy them into your workspace, and share your own for review."
url: https://onesend.email/docs/api-reference/gallery/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# 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.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## 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

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

application/json, required.

| 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. |
| `name`required | `string` |  |
| `description`required | `string` |  |
| `category`required | `"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. |
| `consent`required | `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

`201` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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 |
|---|---|---|---|
| `slug`required | path | `string` |  |

### Responses

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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 |
|---|---|---|---|
| `slug`required | path | `string` |  |

### Responses

`200` Success (text/html)

**Errors: 400, 404, 429, 500**

- `400` Invalid 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`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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 |
|---|---|---|---|
| `slug`required | path | `string` |  |

### Responses

`200` Success

```
{
  "ok": true,
  "uses": number
}
```

**Errors: 400, 404, 409, 429, 500**

- `400` Invalid 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`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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 |
|---|---|---|---|
| `slug`required | path | `string` |  |

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `name` | `string` |  |
| `slug` | `string` |  |

### Responses

`201` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
