# List sample emails and theme presets

`GET /v1/templates/gallery`

Requires an API key with the `templates:read` scope. [About keys and scopes](/docs/api/authentication)

Finished sample emails and coordinated theme presets, the same for every workspace. Start a template from a sample by creating it with the sample's `theme` and `blocks`; apply a preset by replacing a template's `theme`. Photos are served from Unsplash under its licence.

## Returns

Returns `200 OK` with a `TemplateGallery` in `data`. Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `presets` (object[], required) — Ready-made themes to start from.
  - `id` (string, required)
  - `name` (string, required)
  - `theme` (EmailTheme, required)
    - `font` (string, optional, up to 200 characters) — Body font stack, such as `Inter, sans-serif`.
    - `hfont` (string, optional, up to 200 characters) — Heading font stack.
    - `bg` (string, optional) — Background of the email card, as hex.
    - `canvas` (string, optional) — Background behind the card, as hex.
    - `text` (string, optional) — Default text colour, as hex.
    - `accent` (string, optional) — Brand colour for buttons and highlights, as hex.
    - `link` (string, optional) — Link colour, as hex.
    - `width` (string, optional, one of `560px`, `600px`, `680px`) — Width of the email card on wide screens.
    - `radius` (string, optional, one of `0px`, `6px`, `12px`, `16px`, `24px`, `999px`) — Corner rounding of the email's card.
    - `btnRadius` (string, optional, one of `0px`, `6px`, `12px`, `16px`, `24px`, `999px`) — Button corners; `radius` rounds the email's card and, when this is unset, buttons.
    - `btn` (string, optional, one of `solid`, `outline`) — Button style.
- `samples` (object[], required) — Example designs to start from.
  - `id` (string, required)
  - `name` (string, required)
  - `description` (string, required)
  - `schemaVersion` (integer, required, min > 0, max 1000)
  - `theme` (EmailTheme, required)
    - `font` (string, optional, up to 200 characters) — Body font stack, such as `Inter, sans-serif`.
    - `hfont` (string, optional, up to 200 characters) — Heading font stack.
    - `bg` (string, optional) — Background of the email card, as hex.
    - `canvas` (string, optional) — Background behind the card, as hex.
    - `text` (string, optional) — Default text colour, as hex.
    - `accent` (string, optional) — Brand colour for buttons and highlights, as hex.
    - `link` (string, optional) — Link colour, as hex.
    - `width` (string, optional, one of `560px`, `600px`, `680px`) — Width of the email card on wide screens.
    - `radius` (string, optional, one of `0px`, `6px`, `12px`, `16px`, `24px`, `999px`) — Corner rounding of the email's card.
    - `btnRadius` (string, optional, one of `0px`, `6px`, `12px`, `16px`, `24px`, `999px`) — Button corners; `radius` rounds the email's card and, when this is unset, buttons.
    - `btn` (string, optional, one of `solid`, `outline`) — Button style.
  - `blocks` (EmailBlock[], required, at least 1 item, at most 200 items) — At most 200 blocks across the entire tree and five levels including the root. Footer blocks must remain at root. Known child fields are validated recursively.
    - `id` (string, required, 1–128 characters) — Identifies the block within the template; unique among its blocks.
    - `type` (string, required, 1–64 characters) — The block type: `header`, `heading`, `text`, `image`, `button`, `divider`, `spacer`, `columns`, `columns3`, `imagetext`, `imagegroup`, `boxed`, `quote`, `list`, `product`, `video`, `social`, `menu`, `html`, `section`, `footer`, `repeat`, `shared`. Each type reads its own fields next to `type`; an unknown type is kept but not validated.
    - `style` (EmailBlockStyle, optional) — Visual overrides for this block, such as colours, font and spacing.
      - `backgroundColor` (string, optional) — Fill behind the block.
      - `fontFamily` (string, optional, one of `Arial`, `Verdana`, `Georgia`, `Tahoma`, `Times New Roman`, `Courier New`, `Inter`, `Roboto`, `Open Sans`, `Lato`, `Montserrat`, `Poppins`, `DM Sans`, `Nunito`, `Work Sans`, `Oswald`, `Playfair Display`, `Merriweather`, `Lora`, `Libre Baskerville`, `EB Garamond`) — A font every client has (Arial, Verdana, Georgia, Tahoma, Times New Roman, Courier New), or a web font, which shows where the client loads it and falls back to a safe font elsewhere.
      - `fontSize` (integer, optional, min 12, max 72) — Text size in px, 12 to 72.
      - `mobileFontSize` (integer, optional, min 12, max 72) — Text size in px on phones (screens up to 620px), 12 to 72.
      - `padding` (object, optional) — Space inside the block in px, 0 to 100 per side; omitted sides keep their default.
        - `top` (integer, optional, min 0, max 100)
        - `right` (integer, optional, min 0, max 100)
        - `bottom` (integer, optional, min 0, max 100)
        - `left` (integer, optional, min 0, max 100)
      - `borderWidth` (integer, optional, min 0, max 10) — Border thickness in px; 0 for none.
      - `borderStyle` (string, optional, one of `solid`, `dashed`, `dotted`) — Border line style.
      - `borderColor` (string, optional) — Border colour.
      - `borderRadius` (integer, optional, min 0, max 100) — Corner rounding in px, 0 to 100.
      - `textColor` (string, optional) — Text colour.
      - `linkColor` (string, optional) — Colour of links in the text.
      - `letterSpacing` (number, optional, min -2, max 20) — Space between letters in px, such as 3 for a spaced-out eyebrow line.
      - `textTransform` (string, optional, one of `none`, `uppercase`) — Set to `uppercase` to capitalise all text.
      - `lineHeight` (number, optional, min 1, max 3) — A multiple of the font size.
      - `fontWeight` (string, optional, one of `regular`, `bold`) — Text weight.
      - `fontStyle` (string, optional, one of `normal`, `italic`) — Text style.
      - `inset` (boolean, optional) — Draw the background and border as a box within the content width, not across the whole row.
    - `visibleIf` (object, optional) — Show the block only to contacts these segment rules match, checked as each message is rendered. Omit to show it to everyone. Not allowed on the footer.
      - One of: **Match all**
        - `all` (object[], required, at least 1 item, at most 20 items) — Every rule or nested group must match.
      - One of: **Match any**
        - `any` (object[], required, at least 1 item, at most 20 items) — At least one rule or nested group must match.
    - `showOn` (string, optional, one of `mobile`, `desktop`) — Show the block only on phones (screens up to 620px) or only on wider screens. Clients that ignore screen size show the desktop version, and so does plain text. Omit to show it everywhere. Not allowed on the footer.
    - `columns` (object[][], optional, at most 3 items) — Nested child block arrays: exactly two for columns, three for columns3. Each child follows this block contract. Omit to retain legacy text columns.
    - `blocks` (object[], optional, at most 200 items) — A section's child blocks, drawn inside its box; or a repeat block's, written out once per item of its `list`, where `{{ item.<field> }}` reads that item. Repeats do not nest.
  - `thumbnailUrl` (string, required, uri) — A 320 × 427 WebP picture of the sample, its wordmark reading "Your Brand".

## Example

```bash
curl https://api.kirora.io/v1/templates/gallery \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": {
    "presets": [
      {
        "id": "id_example",
        "name": "Weekend specials",
        "theme": {}
      }
    ],
    "samples": [
      {
        "id": "id_example",
        "name": "Weekend specials",
        "description": "description_example",
        "schemaVersion": 1,
        "theme": {},
        "blocks": [
          {
            "id": null,
            "type": null
          }
        ],
        "thumbnailUrl": "https://example.com"
      }
    ]
  }
}
```