**גרסאות API** · [V2 (Latest)](/integrations/v2/docs?lang=he) · **V1**

> **גרסה זו של ה־API מיושנת.** לחיבורים חדשים יש להשתמש בגרסה העדכנית ביותר. [לתיעוד העדכני](/integrations/v2/docs?lang=he)

# Email Template Catalogue

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

AI-first global email-template library. `/email-templates/catalog*` is organisation-independent and accepts only the dedicated `kc_live_*` system token. `/email-templates/library*` lets every organisation browse, preview with its own branding, and import published models. The system token is limited to `email_template_catalog:read|write|publish` and cannot access client data.

## פעולות

## GET /email-templates/catalog/variables

List supported email variables

`list_email_template_variables`

Required system scope: `email_template_catalog:read`. Returns the only variables an AI may use. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:read",
  "additional": []
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateVariableCatalogue"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "CATALOG_SYSTEM_KEY_REQUIRED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CATALOG_SYSTEM_KEY_REQUIRED"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /email-templates/catalog/assets

Upload an image for catalogue emails

`upload_catalog_email_template_asset`

Required system scope: `email_template_catalog:write`. Accepts PNG, JPEG or WebP as base64, validates the real image bytes and returns a stable HTTPS URL for use in HTML. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/EmailTemplateCatalogAssetInput"
      }
    }
  }
}
```

### תגובות

#### HTTP 201

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateCatalogAsset"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /email-templates/catalog

List catalogue drafts and published templates

`list_catalog_email_templates`

Required system scope: `email_template_catalog:read`. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "status",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "DRAFT",
      "PUBLISHED"
    ]
  }
}
```

```json
{
  "name": "language",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "search",
  "in": "query",
  "schema": {
    "type": "string",
    "maxLength": 100
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailTemplateCatalogItem"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /email-templates/catalog

Create a complete catalogue draft

`create_catalog_email_template`

Required system scope: `email_template_catalog:write`. Creates HTML and catalogue metadata together, then returns validation results. The template remains a DRAFT until explicitly published. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/EmailTemplateCatalogCreateInput"
      }
    }
  }
}
```

### תגובות

#### HTTP 201

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateCatalogItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "CATALOG_SYSTEM_KEY_REQUIRED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CATALOG_SYSTEM_KEY_REQUIRED"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /email-templates/catalog/{id}

Get a catalogue template and its validation

`get_catalog_email_template`

Required system scope: `email_template_catalog:read`. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateCatalogItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /email-templates/catalog/{id}

Update catalogue metadata

`update_catalog_email_template`

Required system scope: `email_template_catalog:write`. Returns the template to DRAFT. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/EmailTemplateCatalogUpdateInput"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateCatalogItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## DELETE /email-templates/catalog/{id}

Delete a catalogue template

`delete_catalog_email_template`

Required system scope: `email_template_catalog:write`. Soft-deletes the draft or published template. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## PUT /email-templates/catalog/{id}/content

Replace catalogue HTML

`update_catalog_email_template_content`

Required system scope: `email_template_catalog:write`. Returns the template to DRAFT and returns validation results. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/EmailTemplateCatalogContentInput"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateCatalogItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /email-templates/catalog/{id}/validate

Validate a catalogue template

`validate_catalog_email_template`

Required system scope: `email_template_catalog:read`. Checks required metadata, unknown variables, unsubscribe link, unsafe HTML and common email-client layout problems. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateValidation"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /email-templates/catalog/{id}/preview-link

Create a browser preview URL

`create_catalog_email_template_preview_link`

Required system scope: `email_template_catalog:read`. Returns a signed URL plus the rendered subject/preheader, valid for 1–60 minutes. The authoring preview uses a harmless synthetic organisation and sample recipient values, so the system key never reads client data. It works for DRAFT and PUBLISHED templates, including drafts with validation errors or compatibility warnings. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": false,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/EmailTemplatePreviewLinkInput"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplatePreviewLink"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "EMAIL_TEMPLATE_PREVIEW_NOT_CONFIGURED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "EMAIL_TEMPLATE_PREVIEW_NOT_CONFIGURED"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:read",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /email-templates/catalog/{id}/publish

Publish a validated catalogue template

`publish_catalog_email_template`

Required system scope: `email_template_catalog:publish`. Publication is rejected when validation contains any error. Success increments the immutable catalogue version visible to clients. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:publish",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateCatalogItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "CATALOG_VALIDATION_FAILED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CATALOG_VALIDATION_FAILED"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CATALOG_CHANGED_DURING_PUBLICATION",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CATALOG_CHANGED_DURING_PUBLICATION"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:publish",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /email-templates/catalog/{id}/unpublish

Return a catalogue template to draft

`unpublish_catalog_email_template`

Required system scope: `email_template_catalog:publish`. Removes the template from the client catalogue without deleting it. This global endpoint accepts only the dedicated organisation-less `kc_live_*` catalogue token.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_template_catalog:publish",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_template_catalog:publish",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /email-templates/library

Browse published email templates

`list_published_email_templates`

Required scope: `email_templates:read`. Available to every organisation. Returns only PUBLISHED templates and reports whether the current version was already imported into the caller's organisation.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_templates:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "language",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "category",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "search",
  "in": "query",
  "schema": {
    "type": "string",
    "maxLength": 100
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailTemplateCatalogItem"
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_templates:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /email-templates/library/{id}

Get one published email template

`get_published_email_template`

Required scope: `email_templates:read`. Returns the published source including its HTML variables. Use the preview-link operation to render it with the current organisation's branding.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_templates:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplateCatalogItem"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_templates:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /email-templates/library/{id}/preview-link

Preview a published template with my branding

`create_published_email_template_preview_link`

Required scope: `email_templates:read`. Returns a signed browser URL. The target organisation is always the API key's organisation and cannot be overridden.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_templates:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### גוף הבקשה

```json
{
  "required": false,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "expiresInSeconds": {
            "type": "integer",
            "minimum": 60,
            "maximum": 3600,
            "default": 900
          }
        }
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplatePreviewLink"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "EMAIL_TEMPLATE_PREVIEW_NOT_CONFIGURED",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "EMAIL_TEMPLATE_PREVIEW_NOT_CONFIGURED"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_templates:read",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /email-templates/library/{id}/import

Import a published template into my organisation

`import_published_email_template`

Required scope: `email_templates:write`. Creates an autonomous AI template in the caller's organisation. All `{{org.*}}` variables are resolved from that organisation; recipient variables remain for send time. Importing the same published version twice is idempotent.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "email_templates:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Already imported",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/EmailTemplateImportResult"
      }
    }
  }
}
```

#### HTTP 201

```json
{
  "description": "Imported",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/EmailTemplateImportResult"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "email_templates:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## סכמות

```json
{
  "components": {
    "schemas": {
      "EmailTemplateVariableCatalogue": {
        "type": "object",
        "properties": {
          "organisation": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailTemplateVariableDefinition"
            }
          },
          "recipient": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailTemplateVariableDefinition"
            }
          }
        }
      },
      "EmailTemplateVariableDefinition": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "example": "org.logoUrl"
          },
          "token": {
            "type": "string",
            "example": "{{org.logoUrl}}"
          },
          "description": {
            "type": "string"
          },
          "resolvedAt": {
            "type": "string",
            "enum": [
              "preview_and_import",
              "send"
            ]
          },
          "example": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "EmailTemplateCatalogAssetInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data"
        ],
        "description": "Upload an email image from raw base64 or a data URL. Use the returned HTTPS URL in catalogue HTML. Maximum decoded size: 5 MB.",
        "properties": {
          "data": {
            "type": "string",
            "format": "byte",
            "description": "Raw base64 image data, or a complete data:image/...;base64,... URL."
          },
          "mimeType": {
            "type": "string",
            "enum": [
              "image/png",
              "image/jpeg",
              "image/jpg",
              "image/webp"
            ]
          },
          "name": {
            "type": "string",
            "maxLength": 160
          }
        }
      },
      "EmailTemplateCatalogAsset": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "filename": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "mimeType": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "EmailTemplateCatalogItem": {
        "type": "object",
        "description": "A global source stored in the dedicated email_template_catalog collection. It is not an organisation's personal email template until imported.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true
          },
          "name": {
            "type": "string"
          },
          "editorType": {
            "type": "string",
            "enum": [
              "AI"
            ],
            "readOnly": true
          },
          "html": {
            "type": "string",
            "nullable": true
          },
          "thumbnailUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "readOnly": true
          },
          "catalog": {
            "$ref": "#/components/schemas/EmailTemplateCatalogMetadata"
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "editDatetime": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "readOnly": true
          },
          "alreadyImported": {
            "type": "boolean",
            "readOnly": true
          }
        }
      },
      "EmailTemplateCatalogMetadata": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "DRAFT",
              "PUBLISHED"
            ],
            "readOnly": true
          },
          "language": {
            "type": "string",
            "pattern": "^[a-z]{2,3}(-[a-z]{2})?$",
            "example": "fr",
            "description": "Language of this template. Create one template per language."
          },
          "category": {
            "type": "string",
            "maxLength": 80,
            "example": "Remerciements"
          },
          "subject": {
            "type": "string",
            "maxLength": 180,
            "description": "Suggested email subject; organisation variables are supported."
          },
          "preheader": {
            "type": "string",
            "maxLength": 240,
            "description": "Optional inbox preview text; organisation variables are supported."
          },
          "description": {
            "type": "string",
            "maxLength": 600,
            "description": "Client-facing explanation of when to use this template."
          },
          "familyKey": {
            "type": "string",
            "maxLength": 100,
            "description": "Stable key shared by translations of the same template, e.g. donation-thanks."
          },
          "tags": {
            "type": "array",
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "maxLength": 60
            }
          },
          "version": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "readOnly": true
          }
        }
      },
      "EmailTemplateCatalogCreateInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "html",
          "language",
          "category",
          "subject"
        ],
        "description": "Create a complete catalogue DRAFT in one call.\n\nEmail-client compatibility rules:\n- Send a COMPLETE UTF-8 HTML document with `<!doctype html>`, `<html>`, `<head>` and `<body>`.\n- Build the layout with presentation tables (`<table role=\"presentation\">`, `<tr>`, `<td>`), never flexbox or CSS grid.\n- Keep the main email at 600px maximum and centred on a neutral full-width background.\n- Put critical styles inline. Do not depend on CSS classes, web fonts, external stylesheets, background images or hover effects; Outlook and some webmail clients strip them.\n- Give every `<img>` explicit numeric `width` and `height` HTML attributes, meaningful `alt` text, and a safe HTTPS source or `{{org.logoUrl}}`.\n- Use only Arial, Helvetica and sans-serif for critical copy.\n- Include a hidden preheader, a branded header, a readable body and a legal footer containing `{{mailing_unsubscribe}}`.\n- Never include scripts, event handlers, iframes, forms, objects, embeds or `javascript:` URLs.\n- A draft can always be previewed. Before publishing, call validation and resolve every error plus compatibility warning for the most reliable Gmail/Apple Mail/Outlook result.\n\nVariable rules:\n- Use only variables returned by `list_email_template_variables`.\n- Organisation variables use harmless sample branding in the authoring preview, then are resolved from the authenticated client organisation during client preview/import.\n- Recipient variables `{{firstname}}`, `{{lastname}}`, `{{hebrewname}}` and `{{mailing_unsubscribe}}` must remain in the stored HTML and are resolved only when an email is sent. Legacy aliases `{{prenom}}`, `{{nom}}` and `{{prenomHE}}` remain supported; prefer the canonical tokens for new templates.\n- `{{mailing_unsubscribe}}` is mandatory in the footer.\n- Never paste a real client's name, logo URL, address, phone or website into a central template.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 160,
            "description": "Internal catalogue name."
          },
          "html": {
            "type": "string",
            "maxLength": 2000000,
            "description": "Complete HTML email. Follow every email-client compatibility and variable rule above."
          },
          "language": {
            "type": "string",
            "pattern": "^[a-z]{2,3}(-[a-z]{2})?$",
            "example": "fr",
            "description": "Language of this template. Create one template per language."
          },
          "category": {
            "type": "string",
            "maxLength": 80,
            "example": "Remerciements"
          },
          "subject": {
            "type": "string",
            "maxLength": 180,
            "description": "Suggested email subject; organisation variables are supported."
          },
          "preheader": {
            "type": "string",
            "maxLength": 240,
            "description": "Optional inbox preview text; organisation variables are supported."
          },
          "description": {
            "type": "string",
            "maxLength": 600,
            "description": "Client-facing explanation of when to use this template."
          },
          "familyKey": {
            "type": "string",
            "maxLength": 100,
            "description": "Stable key shared by translations of the same template, e.g. donation-thanks."
          },
          "tags": {
            "type": "array",
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "maxLength": 60
            }
          }
        }
      },
      "EmailTemplateCatalogUpdateInput": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Update catalogue metadata. Any update returns a published template to DRAFT; publish it again after validation.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 160
          },
          "language": {
            "type": "string",
            "pattern": "^[a-z]{2,3}(-[a-z]{2})?$",
            "example": "fr",
            "description": "Language of this template. Create one template per language."
          },
          "category": {
            "type": "string",
            "maxLength": 80,
            "example": "Remerciements"
          },
          "subject": {
            "type": "string",
            "maxLength": 180,
            "description": "Suggested email subject; organisation variables are supported."
          },
          "preheader": {
            "type": "string",
            "maxLength": 240,
            "description": "Optional inbox preview text; organisation variables are supported."
          },
          "description": {
            "type": "string",
            "maxLength": 600,
            "description": "Client-facing explanation of when to use this template."
          },
          "familyKey": {
            "type": "string",
            "maxLength": 100,
            "description": "Stable key shared by translations of the same template, e.g. donation-thanks."
          },
          "tags": {
            "type": "array",
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "maxLength": 60
            }
          }
        }
      },
      "EmailTemplateCatalogContentInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "html"
        ],
        "description": "Replace the complete HTML and return the template to DRAFT.\n\nEmail-client compatibility rules:\n- Send a COMPLETE UTF-8 HTML document with `<!doctype html>`, `<html>`, `<head>` and `<body>`.\n- Build the layout with presentation tables (`<table role=\"presentation\">`, `<tr>`, `<td>`), never flexbox or CSS grid.\n- Keep the main email at 600px maximum and centred on a neutral full-width background.\n- Put critical styles inline. Do not depend on CSS classes, web fonts, external stylesheets, background images or hover effects; Outlook and some webmail clients strip them.\n- Give every `<img>` explicit numeric `width` and `height` HTML attributes, meaningful `alt` text, and a safe HTTPS source or `{{org.logoUrl}}`.\n- Use only Arial, Helvetica and sans-serif for critical copy.\n- Include a hidden preheader, a branded header, a readable body and a legal footer containing `{{mailing_unsubscribe}}`.\n- Never include scripts, event handlers, iframes, forms, objects, embeds or `javascript:` URLs.\n- A draft can always be previewed. Before publishing, call validation and resolve every error plus compatibility warning for the most reliable Gmail/Apple Mail/Outlook result.\n\nVariable rules:\n- Use only variables returned by `list_email_template_variables`.\n- Organisation variables use harmless sample branding in the authoring preview, then are resolved from the authenticated client organisation during client preview/import.\n- Recipient variables `{{firstname}}`, `{{lastname}}`, `{{hebrewname}}` and `{{mailing_unsubscribe}}` must remain in the stored HTML and are resolved only when an email is sent. Legacy aliases `{{prenom}}`, `{{nom}}` and `{{prenomHE}}` remain supported; prefer the canonical tokens for new templates.\n- `{{mailing_unsubscribe}}` is mandatory in the footer.\n- Never paste a real client's name, logo URL, address, phone or website into a central template.",
        "properties": {
          "html": {
            "type": "string",
            "maxLength": 2000000
          }
        }
      },
      "EmailTemplateValidation": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailTemplateValidationIssue"
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailTemplateValidationIssue"
            }
          },
          "variables": {
            "type": "object",
            "properties": {
              "used": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "organisation": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "recipient": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "unknown": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "EmailTemplateValidationIssue": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "variables": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "EmailTemplatePreviewLinkInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "expiresInSeconds": {
            "type": "integer",
            "minimum": 60,
            "maximum": 3600,
            "default": 900
          }
        }
      },
      "EmailTemplatePreviewLink": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Short-lived signed URL that can be opened directly in a browser without API headers."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "previewContext": {
            "type": "string",
            "enum": [
              "SAMPLE",
              "ORGANISATION"
            ]
          },
          "targetOrganisationId": {
            "type": "string",
            "nullable": true
          },
          "subject": {
            "type": "string",
            "description": "Subject rendered with the target organisation when returned by a client-library preview."
          },
          "preheader": {
            "type": "string",
            "description": "Preheader rendered with the target organisation when returned by a client-library preview."
          }
        }
      },
      "EmailTemplateImportResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/EmailTemplate"
          },
          "alreadyImported": {
            "type": "boolean",
            "description": "True when this exact published version had already been imported; no duplicate was created."
          }
        }
      },
      "EmailTemplate": {
        "type": "object",
        "description": "A reusable HTML email template (collection email_templates). The full HTML email an org can reuse — e.g. linked to a campaign as the donor thank-you email (`campagnes.config.donorEmailTemplate`). `design`/`assets` are the internal editor structures (exposed read-only).",
        "properties": {
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "Display name of the template."
          },
          "editorType": {
            "type": "string",
            "enum": [
              "EDITOR",
              "AI"
            ],
            "description": "Which editor produced it: EDITOR (visual builder, stores `design`) or AI (AI editor, stores `assets`)."
          },
          "html": {
            "type": "string",
            "nullable": true,
            "description": "The complete HTML email."
          },
          "design": {
            "type": "object",
            "nullable": true,
            "readOnly": true,
            "description": "Visual-builder serialization (read-only; EDITOR templates only).",
            "additionalProperties": true
          },
          "assets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "readOnly": true,
            "description": "Asset identifiers embedded by the AI editor (read-only)."
          },
          "thumbnailUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "readOnly": true,
            "description": "Public URL of the auto-generated PNG preview (best-effort; null if not generated)."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "editDatetime": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "readOnly": true
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "parameters": {
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "description": "Resource id — must be a UUID. A malformed id is rejected with 400 INVALID_UUID (it is not just a 404). Need a fresh one? Call GET /utils/uuid."
      }
    }
  }
}
```
