Email layouts

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.

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>
  <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.

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 (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:

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.

REST API

Layouts are managed under /v2/layouts, authenticated with an ApiKey like the rest of the REST API. Each operation has a page in the API reference.

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:

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>"
      }
    }
  }'