# Create a shared block

`POST /v1/shared-blocks`

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

Any member. A shared block (a footer, a product card) is kept once and placed in emails as a `shared` block naming it. Templates and draft campaigns and journeys show its current content; scheduling or sending a campaign, activating a journey and publishing a template keep it as it was then. A placement with `override` shows its own blocks instead: the editor marks it edited and can push it back (update the shared block, then drop the override) or revert it (drop the override).

## Request body

- `name` (string, required, 1–255 characters)
- `blocks` (EmailBlockInput[], 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` (EmailBlockStyleInput, 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.

## Returns

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

- `id` (string, required, uuid)
- `name` (string, required)
- `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.
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)

## Example

```bash
curl -X POST https://api.kirora.io/v1/shared-blocks \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend specials",
    "blocks": [
      {
        "id": "id_example",
        "type": "type_example"
      }
    ]
  }'
```

Response `201`:

```json
{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "name": "Weekend specials",
    "blocks": [
      {
        "id": "id_example",
        "type": "type_example"
      }
    ],
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z"
  }
}
```