Unlayer

https://docs.unlayer.com/
Admin
Unlayer provides embeddable content builders for email, pages, documents, and popups, offering a...
Tokens:376,492
Snippets:3,275
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick Start: install, authenticate, scaffold, pull

Source: https://docs.unlayer.com/cli

Quick Start walkthrough: install the CLI globally, authenticate via browser, scaffold a new project with `unlayer init my-app`, or pull templates from an existing project with `unlayer pull`.

```bash
# 1. Install  
npm install -g @unlayer/cli  
  
# 2. Authenticate (opens browser)  
unlayer login  
  
# 3. Scaffold a project  
unlayer init my-app  
  
# 4. Or pull templates from an existing project  
unlayer pull  

```

--------------------------------

### Quick start: render a WelcomeEmail with @unlayer/react-elements

Source: https://docs.unlayer.com/elements

Quick start example showing how to compose an email with Unlayer Elements and render it to HTML using renderToHtml. Requires React 18+ and the @unlayer/react-elements package.

```jsx
import {  
  Email,  
  Row,  
  Column,  
  ColumnLayouts,  
  Heading,  
  Paragraph,  
  Button,  
  renderToHtml,  
} from '@unlayer/react-elements';  
  
function WelcomeEmail() {  
  return (  
    <Email backgroundColor="#f0f0f0" contentWidth="600px">  
      <Row  
        layout={ColumnLayouts.OneColumn}  
        backgroundColor="#ffffff"  
        padding="20px"  
      >  
        <Column>  
          <Heading fontSize="24px">Welcome!</Heading>  
          <Paragraph html="Thanks for signing up." fontSize="14px" />  
          <Button  
            href="https://example.com"  
            backgroundColor="#0879A1"  
            color="#ffffff"  
          >  
            Get Started  
          </Button>  
        </Column>  
      </Row>  
    </Email>  
  );  
}  
  
const html = renderToHtml(<WelcomeEmail />);  

```

--------------------------------

### Try a Prompt with Your AI Assistant

Source: https://docs.unlayer.com/ai/skills/getting-started/install-skill

Example prompt to try after installation. The AI assistant should respond with a complete, working integration including proper ref handling, ready-event listeners, and save/load patterns.

```text
How do I add Unlayer to my React app?  
```

--------------------------------

### Response sample for GET /v3/me/subscription

Source: https://docs.unlayer.com/server/cloud-api/reference

Example response for GET /v3/me/subscription. Contains plan name, status, expiration, feature availability, and limits. Used to answer plan-related questions with ground-truth data.

```json
{
  "data": {
    "planName": "string",
    "status": "string",
    "expiresAt": "string",
    "features": [
      {
        "name": "string",
        "available": true
      }
    ],
    "limits": [
      {
        "name": "string",
        "value": 0,
        "unit": "string"
      }
    ]
  }
}
```

--------------------------------

### Installation permission error example

Source: https://docs.unlayer.com/cli/errors

Example of an EACCES error during global npm install of the CLI.

```bash
npm install -g @unlayer/cli

# → EACCES: permission denied
```

--------------------------------

### unlayer login examples

Source: https://docs.unlayer.com/cli/commands/auth

Examples of the unlayer login command: interactive browser login, token-based login for CI, auto-selecting workspace and project, and manual token entry. Tokens must start with unlayer_pat_.

```bash
# Interactive browser login  

unlayer login  

# Login with a token (CI-friendly)  

unlayer login --token unlayer_pat_xxxxxxxxxxxx  

# Auto-select workspace and project (great for scripts)  

unlayer login --token $UNLAYER_PAT --workspace-id 42 --project-id 17  

# Manual token entry (no browser available)  

unlayer login --manual  
```

--------------------------------

### Install react-email-editor

Source: https://docs.unlayer.com/builder/document-builder/quickstart

Install the React wrapper for the Unlayer editor.

```bash
npm install react-email-editor
```

--------------------------------

### unlayer whoami example

Source: https://docs.unlayer.com/cli/commands/auth

Example of the unlayer whoami command and its output showing authentication details, current context, and accessible workspaces.

```bash
unlayer whoami  

#  Authentication  

#    Token:   unlayer_pat_xxxxxxxx...  

#    Source:  Config file  

#    API URL: https://api.unlayer.com  

#  

#  Current Context  

#    Workspace: #42  

#    Project:   #17  

#  

#  Accessible Workspaces  

#    ├ Acme (ID: 42)  

#    └ Side Project (ID: 51)  

#  

#  Authentication verified  
```

--------------------------------

### Install Node 20 with nvm

Source: https://docs.unlayer.com/cli/errors

Use nvm to install and use Node 20 or later, required by the CLI.

```bash
nvm install 20

nvm use 20
```

--------------------------------

### Install Unlayer Skills for Windsurf

Source: https://docs.unlayer.com/ai/skills/getting-started/using-with-other-tools

Installs Unlayer Skills for Windsurf using npx. Skills are installed to .windsurf/skills/ in the project directory.

```bash
npx skills add unlayer/unlayer-skills --agent windsurf
```

--------------------------------

### Install Unlayer Skills for GitHub Copilot

Source: https://docs.unlayer.com/ai/skills/getting-started/using-with-other-tools

Installs Unlayer Skills for GitHub Copilot using npx. Skills are installed to .agents/skills/ in the project directory.

```bash
npx skills add unlayer/unlayer-skills --agent copilot
```

--------------------------------

### Complete Unlayer Example

Source: https://docs.unlayer.com/start/frameworks/vanilla-js

Complete example combining the embed script, editor initialization, and export/save buttons in a single HTML page.

```html
<!DOCTYPE html>  

<html>  

  <head>  

    <title>Unlayer Editor</title>  

    <script src="https://editor.unlayer.com/embed.js"></script>  

  </head>  

  <body>  

    <div style="padding: 16px;">  

      <button id="export-btn">Export HTML</button>  

      <button id="save-btn">Save Design</button>  

    </div>  

    <div id="editor-container" style="height: calc(100vh - 60px);"></div>  

  

    <script>  

      unlayer.init({  

        id: 'editor-container',  

        displayMode: 'email',  

      });  

  

      document  

        .getElementById('export-btn')  

        .addEventListener('click', function () {  

          unlayer.exportHtml(function (data) {  

            console.log('HTML:', data.html);  

          });  

        });  

  

      document  

        .getElementById('save-btn')  

        .addEventListener('click', function () {  

          unlayer.saveDesign(function (design) {  

            console.log('Design:', design);  

          });  

        });  

    </script>  

  </body>  

</html>  


```

--------------------------------

### Verify GitHub Copilot Skills Installation

Source: https://docs.unlayer.com/ai/skills/getting-started/using-with-other-tools

Lists the installed Unlayer skill files in the .agents/skills/ directory to confirm installation.

```bash
ls .agents/skills/unlayer*
```

--------------------------------

### Verify Windsurf Skills Installation

Source: https://docs.unlayer.com/ai/skills/getting-started/using-with-other-tools

Lists the installed Unlayer skill files in the .windsurf/skills/ directory to confirm installation.

```bash
ls .windsurf/skills/unlayer*
```

--------------------------------

### Install vue-email-editor

Source: https://docs.unlayer.com/builder/document-builder/quickstart

Install the Vue wrapper for the Unlayer editor.

```bash
npm install vue-email-editor
```

--------------------------------

### Install Unlayer skills for Cursor

Source: https://docs.unlayer.com/ai/skills/getting-started/using-with-cursor

Run this command to install Unlayer skills for Cursor. Skills are installed to the .agents/skills/ directory in your project.

```bash
npx skills add unlayer/unlayer-skills --agent cursor
```

--------------------------------

### Verify Unlayer skills installation

Source: https://docs.unlayer.com/ai/skills/getting-started/using-with-claude-code

Lists the installed skill folders to confirm the installation. You should see folders: unlayer/, unlayer-integration/, unlayer-image-editor/, unlayer-elements/, unlayer-custom-tools/, unlayer-export/, and unlayer-config/.

```bash
ls .claude/skills/unlayer*
```

--------------------------------

### Install globally with npm, pnpm, or yarn

Source: https://docs.unlayer.com/cli/installation

Install the CLI globally using your preferred package manager. The binary `unlayer` will be added to your PATH.

```bash
npm install -g @unlayer/cli  

# or  

pnpm add -g @unlayer/cli  

# or  

yarn global add @unlayer/cli  
```

--------------------------------

### Install @unlayer/sdk

Source: https://docs.unlayer.com/sdk

Install the official Unlayer SDK package from npm. Requires Node.js 20+.

```bash
npm install @unlayer/sdk  
```

--------------------------------

### Install @unlayer/react-elements with npm, pnpm, or yarn

Source: https://docs.unlayer.com/elements/react/installation

Install the package using your preferred package manager. The commands are alternatives; choose one.

```bash
npm install @unlayer/react-elements  

# or  

pnpm add @unlayer/react-elements  

# or  

yarn add @unlayer/react-elements  
```

--------------------------------

### Verify installation with renderToHtml

Source: https://docs.unlayer.com/elements/react/installation

Renders a simple Email component to an HTML string. If you see an HTML string, the installation is successful.

```tsx
import {
  Email,
  Row,
  Column,
  ColumnLayouts,
  Paragraph,
  renderToHtml,
} from '@unlayer/react-elements';

const html = renderToHtml(
  <Email>
    <Row layout={ColumnLayouts.OneColumn}>
      <Column>
        <Paragraph>It works!</Paragraph>
      </Column>
    </Row>
  </Email>,
);

console.log(html);
```

--------------------------------

### Specify everything inline

Source: https://docs.unlayer.com/cli/commands/init

Use `unlayer init` with project name, `-f` for framework, and `-t` for template to avoid prompts.

```bash
unlayer init my-email-app -f nextjs -t product
```

--------------------------------

### GET /templates/{id}/html

Source: https://docs.unlayer.com/redocusaurus/cloud-api-v2.yaml

This snippet documents the deprecated GET endpoint for rendering a template's HTML. It includes the path parameter, response schema, and example response.

```APIDOC
## GET /templates/{id}/html

### Description
Render a template HTML. This endpoint retrieves the HTML of a template by its ID. It is deprecated.

### Method
GET

### Endpoint
/templates/{id}/html

### Parameters
#### Path Parameters
- **id** (string) - Required - ID of the template to retrieve

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Contains the template data
  - **html** (string) - HTML
  - **chunks** (object) - Chunks
    - **body** (string) - Body
    - **css** (string) - CSS
    - **js** (string) - JS
    - **fonts** (array) - Fonts
    - **tags** (array) - Tags
  - **amp** (object) - AMP
    - **enabled** (boolean) - Enabled
    - **format** (string) - Format
    - **validation** (object) - Validation
      - **status** (string) - Status
      - **errors** (array) - Errors

#### Response Example
{
  "success": true,
  "data": {
    "html": "<html>...</html>",
    "chunks": {
      "body": "...",
      "css": "...",
      "js": "...",
      "fonts": [],
      "tags": []
    },
    "amp": {
      "enabled": false,
      "format": "...",
      "validation": {
        "status": "...",
        "errors": []
      }
    }
  }
}
```

--------------------------------

### Set default button style without Style Guide

Source: https://docs.unlayer.com/builder/styleguide

Defines a default background color for buttons when no Style Guide is applied. This example uses a green background as the default.

```javascript
unlayer.init({  

  tools: {  

    button: {  

      properties: {  

        buttonColors: {  

          editor: {  

            defaultValue: {  

              backgroundColor: 'green',  

              // ...  

            },  

          },  

        },  

      },  

    },  

  },  

});  
```

--------------------------------

### Initialize a new project with unlayer init

Source: https://docs.unlayer.com/cli/quick-reference

Create a new project with a specified framework and template. Supports options for skipping install, TypeScript, and connecting to a workspace/project.

```bash
unlayer init [name] [-f <framework>] [-t <template>] [options]  
```

--------------------------------

### Initialize Unlayer with version option

Source: https://docs.unlayer.com/builder/version-management

Shows how to pass the version option to unlayer.init() to select a release channel or specific version. The default is 'stable'.

```javascript
unlayer.init({  

  version: 'latest', // Specify 'stable' or a specific version number  

});  
```

--------------------------------

### GET /v3/projects/{id} - 200 Response

Source: https://docs.unlayer.com/server/cloud-api/reference

Example JSON response for a successful GET request to retrieve project details. The response includes the project id, name, status, creation timestamp, workspace details, and inbox previews configuration.

```json
{
  "data": {
    "id": 0,
    "name": "string",
    "status": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "workspace": {
      "id": 0,
      "name": "string"
    },
    "inboxPreviews": {
      "clients": null,
      "dataRegion": "us"
    }
  }
}
```

--------------------------------

### Interactive init

Source: https://docs.unlayer.com/cli/commands/init

Run `unlayer init` without arguments to be prompted for project name, framework, template, and account connection.

```bash
unlayer init

# → prompts for name, framework, template, account connection
```

--------------------------------

### Import TypeScript types from @unlayer/react-elements

Source: https://docs.unlayer.com/elements/react/installation

The package ships its own type definitions, so no @types/* install is needed. This example imports several exported types.

```typescript
import type {
  ButtonProps,
  EmailProps,
  PageProps,
  DocumentProps,
  RowProps,
  ColumnLayout,
  HtmlParts,
} from '@unlayer/react-elements';
```

--------------------------------

### List and select a project

Source: https://docs.unlayer.com/cli/errors

Use `unlayer project list` to see available projects and `unlayer project use <id>` to set the active project.

```bash
unlayer project list

unlayer project use <id>
```

--------------------------------

### Get credit balance response

Source: https://docs.unlayer.com/server/cloud-api/ai-credits

Example response from the Get credit balance endpoint. `is_capped` reports whether enforcement can constrain AI usage, not whether Console has a positive allowance to display. When `is_capped` is `false`, usage is metered for visibility but remains uncapped; `reset_date` is the end timestamp for the current credit window, or `null` when the service cannot resolve an active future billing window.

```json
{
  "is_capped": true,
  "credits_total": 10000,
  "credits_used": 7400,
  "credits_remaining": 2600,
  "reset_date": "2026-08-01T00:00:00.000Z"
}
```

--------------------------------

### POST /v3/templates/validate 200 response

Source: https://docs.unlayer.com/server/cloud-api/reference

Example 200 response for POST /v3/templates/validate. Contains success, data.valid, data.migratedFrom, data.errors, and data.errorCount. Note that every checked design gets HTTP 200; data.valid is the source of truth.

```json
{
  "success": true,
  "data": {
    "valid": true,
    "migratedFrom": 0,
    "errors": [
      {
        "path": "string",
        "message": "string",
        "code": "string"
      }
    ],
    "errorCount": 0
  }
}
```

--------------------------------

### Create welcome-email.tsx

Source: https://docs.unlayer.com/elements/react/quickstart

Creates a welcome email component using the wrapper → Row → Column → content structure. This is the first email built in the quickstart.

```tsx
import {
  Email,
  Row,
  Column,
  ColumnLayouts,
  Heading,
  Paragraph,
  Button,
} from '@unlayer/react-elements';

export function WelcomeEmail() {
  return (
    <Email backgroundColor="#f0f0f0" contentWidth="600px">
      <Row
        layout={ColumnLayouts.OneColumn}
        backgroundColor="#ffffff"
        padding="20px"
      >
        <Column>
          <Heading
            headingType="h1"
            fontSize="24px"
            fontFamily={{ label: 'Arial', value: 'arial,helvetica,sans-serif' }}
          >
            Welcome!
          </Heading>
          <Paragraph fontSize="14px">Thanks for signing up.</Paragraph>
          <Button
            href="https://example.com"
            backgroundColor="#0879A1"
            color="#ffffff"
          >
            Get Started
          </Button>
        </Column>
      </Row>
    </Email>
  );
}
```

--------------------------------

### renderToPlainText: Generate plain text from email element

Source: https://docs.unlayer.com/elements/react/rendering-api

Use renderToPlainText to get a plain-text version of an email by rendering to HTML then stripping markup. This is useful for the text/plain MIME part of a multipart email, improving deliverability. The output for this example is "Hello World".

```tsx
import {  
  renderToPlainText,  
  Email,  
  Row,  
  Column,  
  Paragraph,  
} from '@unlayer/react-elements';  
  
const text = renderToPlainText(  
  <Email>  
    <Row>  
      <Column>  
        <Paragraph>Hello World</Paragraph>  
      </Column>  
    </Row>  
  </Email>,  
);  
// "Hello World"  

```

--------------------------------

### Switch between deployments (unlayer env use)

Source: https://docs.unlayer.com/cli/examples

Switches to the self-hosted environment, runs template list and pull, then returns to the default URLs with --none. Comments show the expected source of data for each command.

```bash
unlayer env use self-hosted  

unlayer template list             # → reads from your self-hosted instance  

unlayer pull --design-only  

  

unlayer env use --none            # back to the default URLs  

unlayer template list             # → reads from api.unlayer.com  
```

--------------------------------

### Verify installation with version and status

Source: https://docs.unlayer.com/cli/installation

Run `unlayer --version` and `unlayer status` to verify the installation. `unlayer status` reports authentication state, API reachability and latency, active workspace and project IDs, and the config file path. It works without authentication.

```bash
unlayer --version  

# 0.1.0  

  

unlayer status  
```

--------------------------------

### Full Sample Code: Uploading to /uploads

Source: https://docs.unlayer.com/builder/file-storage/custom

Complete example of registering the image callback and uploading the file to a server endpoint using fetch, then passing the returned URL to Unlayer.

```APIDOC
## Full Sample Code: Uploading to /uploads

### Description
Complete example of registering the image callback and uploading the file to a server endpoint using fetch, then passing the returned URL to Unlayer.

### Method
registerCallback

### Endpoint
POST /uploads

### Parameters
#### Request Body
- **file** (File) - Required - The file to upload, taken from `file.attachments[0]`.

### Request Example
```javascript
unlayer.registerCallback('image', function (file, done) {
  var data = new FormData();
  data.append('file', file.attachments[0]);

  fetch('/uploads', {
    method: 'POST',
    headers: {
      Accept: 'application/json',
    },
    body: data,
  })
    .then((response) => {
      // Make sure the response was valid
      if (response.status >= 200 && response.status < 300) {
        return response;
      } else {
        var error = new Error(response.statusText);
        error.response = response;
        throw error;
      }
    })
    .then((response) => {
      return response.json();
    })
    .then((data) => {
      // Pass the URL back to Unlayer to mark this upload as completed
      done({ progress: 100, url: data.filelink });
    });
});
```

### Response
#### Success Response (200)
- **filelink** (string) - The URL of the uploaded file, used in the `done` callback.

#### Response Example
```json
{
  "filelink": "https://example.com/uploads/file.jpg"
}
```
```

--------------------------------

### CI-friendly non-interactive init

Source: https://docs.unlayer.com/cli/commands/init

In non-interactive mode (CI or `--non-interactive`), all three of `<project-name>`, `--framework`, and `--template` are required. To auto-connect to your account, supply both `--workspace-id` and `--project-id`.

```bash
unlayer init my-app \
  -f nextjs \
  -t blank \
  --workspace-id 42 \
  --project-id 17 \
  --json
```

--------------------------------

### Install Unlayer skills for Codex

Source: https://docs.unlayer.com/ai/skills/getting-started/using-with-codex

Run this command in your project root to install the Unlayer skills for Codex. Skills are installed to the .agents/skills/ directory.

```bash
npx skills add unlayer/unlayer-skills --agent codex  
```

--------------------------------

### Install Unlayer Skills

Source: https://docs.unlayer.com/ai/skills/getting-started/install-skill

Installs Unlayer Skills into your project. The CLI automatically detects your AI tool and installs the skill files in the correct location.

```bash
npx skills add unlayer/unlayer-skills  
```

--------------------------------

### Full sample upload with fetch

Source: https://docs.unlayer.com/builder/file-storage/custom

Complete sample that uploads the file to /uploads using fetch and passes the returned filelink URL to done. Handles HTTP errors and validates the response.

```javascript
unlayer.registerCallback('image', function (file, done) {  

  var data = new FormData();  

  data.append('file', file.attachments[0]);  

  

  fetch('/uploads', {  

    method: 'POST',  

    headers: {  

      Accept: 'application/json',  

    },  

    body: data,  

  })  

    .then((response) => {  

      // Make sure the response was valid  

      if (response.status >= 200 && response.status < 300) {  

        return response;  

      } else {  

        var error = new Error(response.statusText);  

        error.response = response;  

        throw error;  

      }  

    })  

    .then((response) => {  

      return response.json();  

    })  

    .then((data) => {  

      // Pass the URL back to Unlayer to mark this upload as completed  

      done({ progress: 100, url: data.filelink });  

    });  

});  

```

--------------------------------

### unlayer.init()

Source: https://docs.unlayer.com/builder/credit-upsell

Initializes the Unlayer editor with an optional end-user AI allowance snapshot. The `credits` configuration shows the current end user's host-managed allowance inside the builder, warns when the allowance is low, blocks relevant actions when exhausted, and opens a purchase flow without sending the end user away.

```APIDOC
## unlayer.init()

### Description
Initializes the Unlayer editor with an optional end-user AI allowance snapshot. The `credits` configuration shows the current end user's host-managed allowance inside the builder, warns when the allowance is low, blocks relevant actions when exhausted, and opens a purchase flow without sending the end user away.

### Method
init

### Endpoint
unlayer.init(config)

### Parameters
#### Configuration Object
- **id** (string) - Required - The DOM element ID where the editor will be mounted.
- **projectId** (number) - Required - The Unlayer project ID.
- **user** (object) - Required - Object containing the end user identifier.
  - **id** (string) - Required - The end user's unique identifier.
- **credits** (object) - Optional - Host-managed end-user allowance configuration.
  - **ai** (object) - Optional - AI allowance configuration.
    - **limit** (number | null) - Required - Total host allowance. Use `null` for an explicitly uncapped end user.
    - **used** (number) - Required - Amount of the host allowance already consumed.
    - **disabled** (boolean) - Optional - Host override that blocks the resource regardless of the numeric balance.
    - **lowBalanceThresholdPercentage** (number) - Optional - Consumed percentage for the low-balance notice, from `0` to `100`. Defaults to `80`.
    - **unitLabel** (string) - Optional - White-label display unit, such as `credits` or `messages`. Defaults to `credits`.
    - **purchaseUrl** (string) - Optional - Absolute HTTP(S) link-out fallback when no purchase callback is registered.

### Request Example
```javascript
unlayer.init({
  id: 'editor',
  projectId: 1234,
  user: { id: 'customer-42' },
  credits: {
    ai: {
      limit: 100,
      used: 80,
      disabled: false,
      lowBalanceThresholdPercentage: 80,
      unitLabel: 'credits',
      purchaseUrl: 'https://app.example.com/billing/ai',
    },
  },
});
```

### Response
No return value is documented. The configuration takes effect inside the builder UI.
```

--------------------------------

### Quick start: list templates with @unlayer/sdk

Source: https://docs.unlayer.com/sdk

Initialize the SDK with an API key from the UNLAYER_API_KEY environment variable and list the first 10 templates. The SDK also reads UNLAYER_PERSONAL_ACCESS_TOKEN, UNLAYER_PROJECT_ID, and UNLAYER_BASE_URL when the corresponding constructor option is omitted. The default API URL is https://api.unlayer.com; pass baseURL only when targeting another environment.

```typescript
import Unlayer from '@unlayer/sdk';  

const unlayer = new Unlayer({
  apiKey: process.env['UNLAYER_API_KEY'],
});

const page = await unlayer.templates.list({ limit: 10 });

console.info(page.data[0]?.id);
```
Tokens:
Raw