# Email layouts

URL: https://notifly.io/docs/layouts

> Wrap every email in one reusable layout for your header, footer and styling. Add the content variable, pick a layout per step and override it per trigger.

A **layout** is the shared frame around an email: your header, footer, fonts and spacing. You design it once, and each email step then supplies only its own message, which Notifly drops into the layout where you put the `{{content}}` variable. Change the layout and every email that uses it changes with it.

Layouts apply to email steps. They live in each [environment](https://notifly.io/docs/getting-started#environments).

## Create a layout

1. Open **Layouts** in the **Notifications** group of the sidebar.
2. Choose **Create your first layout** (or the create button once you have layouts) and enter a **Layout name**. The **Identifier** is filled in from the name; it is what the API and trigger overrides use to refer to the layout.
3. Design the layout in the editor. It supports a block editor and a raw HTML editor.

The layout body must contain the `{{content}}` variable, which is where the step's email body is inserted. The editor reports an issue on a layout whose body leaves it out. A layout written in the HTML editor must be a complete document, with `<html>` and `<body>` tags.

```html
<html>
  <body>
    <img src="https://example.com/logo.png" alt="Example" />
    {{content}}
    <p>Example Inc. · 1 Main Street</p>
  </body>
</html>
```

Besides `{{content}}`, a layout body can use the `subscriber`, `context` and `env` variables, so a footer can address the recipient or read an [environment variable](https://notifly.io/docs/environment-variables).

## The default layout

The first layout you create in an environment becomes its default layout, badged **Default** in the list. The workflow editor preselects it when you add an email step, and it cannot be deleted (the API answers a delete with `409`). Other layouts can be duplicated and deleted; deleting one removes it from every email step that used it.

## Use a layout in an email step

Open an email step in the workflow editor and use the layout selector at the top of the step. It lists your layouts (the default first, shown as the layout name followed by &#x2A;*(Default)**) and **No layout**. A step renders inside a layout only when one is selected: with **No layout**, the step's body is sent on its own. The selector is editable in the Development environment.

To find out which workflows use a layout before you change or delete it, call `GET /v2/layouts/{layoutId}/usage`.

## Override the layout for one trigger

A trigger can swap or remove the layout for a single send without touching the workflow. Use `overrides` in the trigger request:

```bash
curl -X POST https://api.notifly.io/v1/events/trigger \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<workflow-id>",
    "to": { "subscriberId": "<subscriber-id>" },
    "overrides": {
      "channels": { "email": { "layoutId": "promotional-layout" } },
      "steps": { "<email-step-id>": { "layoutId": null } }
    }
  }'
```

* `overrides.channels.email.layoutId` applies to every email step in the workflow.
* `overrides.steps.<step-id>.layoutId` applies to one step and wins over the channel-level value.
* A `layoutId` of `null` sends the email with no layout.
* Naming a layout that does not exist fails that send, and the activity feed records that the layout was not found.

## Plans and limits

The Free plan includes one layout per environment, which is the default layout; Pro and above can create more. A create request past the limit returns a `400` with the message `Layout limit exceeded. Please contact us to support more layouts.` See [Plans and limits](https://notifly.io/docs/pricing).

## REST API

Layouts are managed under `/v2/layouts`, authenticated with an `ApiKey` like the rest of the [REST API](https://notifly.io/docs/api). Each operation has a page in the [API reference](https://notifly.io/docs/api-reference).

| Operation                                                                           | Request                                                             |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Create a layout](https://notifly.io/docs/api-reference/layouts/LayoutsController_create)                  | `POST /v2/layouts` with `layoutId` and `name`                       |
| [List all layouts](https://notifly.io/docs/api-reference/layouts/LayoutsController_list)                   | `GET /v2/layouts` (`limit` defaults to 50, optional `query` search) |
| [Retrieve a layout](https://notifly.io/docs/api-reference/layouts/LayoutsController_get)                   | `GET /v2/layouts/{layoutId}`                                        |
| [Update a layout](https://notifly.io/docs/api-reference/layouts/LayoutsController_update)                  | `PUT /v2/layouts/{layoutId}` with `name` and the layout body        |
| [Delete a layout](https://notifly.io/docs/api-reference/layouts/LayoutsController__delete)                 | `DELETE /v2/layouts/{layoutId}`                                     |
| [Duplicate a layout](https://notifly.io/docs/api-reference/layouts/LayoutsController_duplicate)            | `POST /v2/layouts/{layoutId}/duplicate`                             |
| [Generate layout preview](https://notifly.io/docs/api-reference/layouts/LayoutsController_generatePreview) | `POST /v2/layouts/{layoutId}/preview`                               |
| [Get layout usage](https://notifly.io/docs/api-reference/layouts/LayoutsController_getUsage)               | `GET /v2/layouts/{layoutId}/usage`                                  |

A layout created through the API starts with an empty block layout. Set its design with an update that carries `controlValues.email`, a `body` string and an `editorType` of `html` or `block`. A body that does not match the editor type is rejected with a `400`:

```bash
curl -X PUT https://api.notifly.io/v2/layouts/brand-layout \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand layout",
    "controlValues": {
      "email": {
        "editorType": "html",
        "body": "<html><body>{{content}}<p>Example Inc.</p></body></html>"
      }
    }
  }'
```
