# Email blocks and designs (/ai/reference/email/email-library)

Toolset `email_library`, 9 tools.

## Records [#records]

### `email_saved_block` [#email_saved_block]

A block the merchant saved for reuse in store emails, newsletters and automations: a content block, or a header or footer that can follow the store style.

- Permission: `content.read`
- Tools: `email_saved_block_list`, `email_saved_block_get`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string |  | one of "content", "header", "footer" |

## Actions [#actions]

### `email_defaults_restore` [#email_defaults_restore]

Add the starter's emails and texts the theme draft lacks; emails it already has stay as they are.

- Action key: `email_defaults.restore`
- Permission: `theme.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID. When omitted, uses the active theme, or the only theme if the store has exactly one. Errors if the choice is ambiguous. |

Example input:

```json
{}
```

### `email_new_design_get` [#email_new_design_get]

What taking the starter's new design would make of an email: its document and texts per language, and whether the merchant's own subject and preheader stay.

Answers not found when the theme offers no new design for this email; email_case_list and the theme tell which emails have one.

- Action key: `email_new_design.get`
- Permission: `theme.read`
- Approval: Runs without approval.
- Effect: Reads only.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID. When omitted, uses the active theme, or the only theme if the store has exactly one. Errors if the choice is ambiguous. |
| `slug` | string | yes | Email case slug (e.g. order-placed). Use email_case_list for the catalog.. at least 1 characters |

Example input:

```json
{
  "slug": "order-placed"
}
```

### `email_new_design_keep` [#email_new_design_keep]

Keep an email as it is and stop offering the starter's new design until the starter changes it again.

- Action key: `email_new_design.keep`
- Permission: `theme.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID. When omitted, uses the active theme, or the only theme if the store has exactly one. Errors if the choice is ambiguous. |
| `slug` | string | yes | Email case slug (e.g. order-placed). Use email_case_list for the catalog.. at least 1 characters |

Example input:

```json
{
  "slug": "order-placed"
}
```

### `email_new_design_take` [#email_new_design_take]

Replace an email in the draft with the starter's new design, keeping the merchant's own subject and preheader.

- Action key: `email_new_design.take`
- Permission: `theme.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes a draft; nothing goes live until it is published.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID. When omitted, uses the active theme, or the only theme if the store has exactly one. Errors if the choice is ambiguous. |
| `slug` | string | yes | Email case slug (e.g. order-placed). Use email_case_list for the catalog.. at least 1 characters |

Example input:

```json
{
  "slug": "order-placed"
}
```

### `email_saved_block_create` [#email_saved_block_create]

Save a block for reuse in store emails, newsletters and automations.

- Action key: `email_saved_block.create`
- Permission: `content.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | 1 to 200 characters |
| `kind` | string |  | content by default. one of "content", "header", "footer" |
| `block` | map of string or number or boolean or list of any value or map of any value or null | yes | One email block, in the shape email_document_get answers blocks with |
| `copy` | map of map of string |  | Texts the block names by key, per language: {"hu": {"heading": "…"}} |
| `linked_to_store_style` | boolean |  | A saved header or footer follows the store style when true |

Example input:

```json
{
  "name": "Holiday hours",
  "block": {
    "id": "text-1",
    "type": "text",
    "text_key": "holiday"
  },
  "copy": {
    "en": {
      "holiday": "We are closed on 24–26 December."
    }
  }
}
```

### `email_saved_block_delete` [#email_saved_block_delete]

Delete a saved email block; emails that placed a copy of it keep their copy.

- Action key: `email_saved_block.delete`
- Permission: `content.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Saved block ID, from email_saved_block_list. at least 1 characters |

Example input:

```json
{
  "id": "019bb28a-18ac-7ff7-a492-89866e738126"
}
```

### `email_saved_block_update` [#email_saved_block_update]

Rename a saved email block or replace its block, texts or kind.

- Action key: `email_saved_block.update`
- Permission: `content.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Saved block ID, from email_saved_block_list. at least 1 characters |
| `name` | string |  | 1 to 200 characters |
| `kind` | string |  | one of "content", "header", "footer" |
| `block` | map of string or number or boolean or list of any value or map of any value or null |  | One email block, in the shape email_document_get answers blocks with |
| `copy` | map of map of string |  | Texts the block names by key, per language: {"hu": {"heading": "…"}} |
| `linked_to_store_style` | boolean |  | A saved header or footer follows the store style when true |

Example input:

```json
{
  "id": "019bb28a-18ac-7ff7-a492-89866e738126",
  "name": "Holiday hours 2026"
}
```