--- title: "Predefined Templates API" description: "Use our API to get a predefined templates from our library of 150+ email templates. Categorized into multiple categires and labeled with handful keywords." url: https://docs.topol.io/email-editor/guide/premade-templates.html --- # Premade templates **The premade templates API serves Topol's library of 150+ ready-made email templates, so you can start from a designed template instead of a blank canvas.** ## What the API covers - **List templates** Return the available premade templates, with paging, a `type` filter (`FREE` or `PRO`), free-text search, filtering by category or keyword IDs, and sorting by date and other columns. - **Get template details** Request one template by ID to get its HTML and JSON. JSON for a `PRO` template is returned only when the request is authenticated with a plugin subscription; otherwise it comes back `null`, while the HTML is always present. - **List categories and keywords** Fetch the category list (Business, E-commerce, and the rest) and the keyword list to build the filters above. Both return `id` and `name`, and the filter parameters take the IDs. ## How it works ### 1\. Get an API key These endpoints take an API key from either your account settings or your existing Plugin API Token. For an account-settings key, open Settings, go to API Tokens, select "Create API Token", and grant the permissions the token needs. To reuse the Plugin API token that initialized your Plugin, copy it from the Plugin settings under "Show API keys". The key unlocks `PRO` template JSON; the list and category endpoints respond without it, so the header is recommended rather than strictly required. ### 2\. Set the request headers Include these headers: ```json { "accept": "application/json", "Authorization": "Bearer " } ``` ## Get premade email templates Retrieve a list of premade email templates. ### Endpoint `GET https://app.topol.io/api/premade-templates` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Request body (required) Request body to get premade templates Content-Type: `application/json` - `visible` _boolean_ — Whether the template must be visible - `published` _boolean_ — Whether the template must be published - `type` _"FREE" | "PRO"_ — Template type - `categories` _integer[]_ — Template category IDs - `keywords` _integer[]_ — Template keyword IDs - `sort_by` _"id" | "order" | "created_at" | "updated_at"_ — Sort column - `sort_by_direction` _"asc" | "desc"_ — Sort direction - `search` _string_ — Search term - `api_token` _string_ — API token ID - `per_page` _integer_ — Number of items per page - `current_page` _integer_ — Current page number ### Responses #### 200 — Templates fetched successfully Content-Type: `application/json` - `success` _boolean_ **required** - `data` _object_ **required** - `data` _object[]_ **required** — List of premade templates - `id` _integer_ — Premade template ID - `name` _string_ — Template display name - `slug` _string_ — Template slug identifier - `type` _string_ — Template type - `img_thumb_url` _string_ — Thumbnail image URL - `category_id` _integer_ — Parent category ID - `description` _string_ — Template description - `keywords` _object[]_ - `id` _integer_ — Keyword ID - `keyword` _string_ — Keyword text value - `slug` _string_ — Keyword slug identifier - `created_at` _string (date-time)_ — Keyword creation timestamp - `updated_at` _string (date-time)_ — Keyword update timestamp - `created_at` _string (date-time)_ — Creation timestamp - `updated_at` _string (date-time)_ — Update timestamp - `total_records` _integer_ — Total number of records available - `current_page` _integer_ — Current page number - `per_page` _integer_ — Number of records per page - `next_page` _integer,null_ — Next page number, if available - `prev_page` _integer,null_ — Previous page number, if available - `last_page` _integer_ — Last page number #### 400 — Bad request. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 401 — Unauthenticated. Content-Type: `application/json` - `message` _string_ **required** — Error message #### 422 — Validation error. Content-Type: `application/json` - `message` _string_ **required** — Main error message - `errors` _object_ **required** — Validation errors keyed by field name - `` _string[]_ #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Get premade email template Get a premade template ### Endpoint `GET https://app.topol.io/api/premade-templates/{premadeTemplate}` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Parameters - `premadeTemplate` (path) _integer_ **required** — Premade template ID ### Responses #### 200 — Template fetched successfully Content-Type: `application/json` - `success` _boolean_ **required** - `data` _object_ **required** - `id` _integer_ — Premade template ID - `name` _string_ — Template display name - `slug` _string_ — Template slug identifier - `type` _"FREE" | "PRO"_ — Template type - `json` _string,null_ — JSON-encoded template data (returned as string, not parsed object). Available only when type is FREE or when user has plugin subscription. - `html` _string,null_ — Rendered HTML email template returned as an encoded string. - `category_id` _integer,null_ — Parent category ID - `order` _integer_ — Ordering value - `description` _string,null_ - `visible` _boolean_ - `created_at` _string (date-time)_ - `updated_at` _string (date-time)_ - `image_path` _string_ - `image_thumb_path` _string_ - `category` _object_ - `id` _integer_ — Category ID - `name` _string_ — Category name - `slug` _string_ — Category slug identifier - `order` _integer_ — Sorting order among categories - `created_at` _string (date-time)_ — Category creation timestamp - `updated_at` _string (date-time)_ — Category update timestamp - `keywords` _object[]_ - `id` _integer_ — Keyword ID - `keyword` _string_ — Keyword text value - `slug` _string_ — Keyword slug identifier - `created_at` _string (date-time)_ — Keyword creation timestamp - `updated_at` _string (date-time)_ — Keyword update timestamp #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Get a list of premade template categories Retrieve a list of premade template categories ### Endpoint `GET https://app.topol.io/api/premade-template-categories` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Responses #### 200 — Template categories fetched successfully Content-Type: `application/json` - `success` _boolean_ **required** - `data` _object[]_ **required** - `id` _integer_ **required** — Category ID - `name` _string_ **required** — Category name - `value` _string_ **required** — Category slug identifier #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message ## Get a list of premade template keywords Retrieve a list of premade template keywords ### Endpoint `GET https://app.topol.io/api/premade-template-keywords` ### Authentication - **BearerAuth** (http bearer) — Use: `Authorization: Bearer ` ### Responses #### 200 — Template keywords fetched successfully Content-Type: `application/json` - `success` _boolean_ **required** - `data` _object[]_ **required** - `id` _integer_ **required** — Keyword ID - `name` _string_ **required** — Keyword text value - `value` _string_ **required** — Keyword slug identifier #### 500 — Internal server error. Content-Type: `application/json` - `message` _string_ **required** — Error message