---
url: "/emailify/design/figma-mcp.md"
description: "The exact frame, component, and metadata contract agents must follow when creating or editing Emailify emails directly in Figma."
---

# Using Emailify with Figma MCP

> The exact frame, component, and metadata contract agents must follow when creating or editing Emailify emails directly in Figma.

This page is the canonical contract for agents that create or edit Emailify emails directly through Figma MCP. Follow the names and structure exactly so Emailify can recognize the result while keeping every component linked to its original main component.

Agents can read the compact [Markdown version of this contract](/emailify/design/figma-mcp.md) without loading the surrounding documentation interface.

> **Note:** This direct-to-Figma workflow is part of AI Designer (BETA). The contract may evolve while the feature is being improved, so agents should read this page before each MCP workflow.

## Agent instruction

Paste this into Codex, Claude Code, or another agent with Figma write access:

```text
Read and follow the current Emailify Figma MCP contract at https://docs.hypermatic.com/emailify/design/figma-mcp.md before writing to Figma. Create or edit the email using only linked Emailify component instances. Preserve protected content, component links, and existing instance overrides. For a new email, create a top-level vertical auto-layout frame named exactly "✉️ Emailify MCP: [email name]" and add only linked Emailify section, wrapper, or hero instances as its direct children. Never detach instances or add raw layers inside the email frame. Create a separate top-level sibling frame named exactly "✉️ Emailify MCP Metadata: [same email name]" with TEXT layers named exactly "Subject Line" and "Preheader Text", containing only their corresponding values. Replace the bracketed placeholders with the actual email name. When finished, tell me to open or refresh Emailify.
```

## Email frame contract

For each new email, create one frame that satisfies every rule below:

| Property | Required value |
| --- | --- |
| Name | `✉️ Emailify MCP: [email name]` |
| Position | Top level on the Figma page, not nested inside another frame or section |
| Layout | Vertical auto layout |
| Direct children | Linked Figma component instances only |
| Allowed Emailify roots | `mj-section`, `mj-wrapper`, or `mj-hero` |
| Content | At least one valid Emailify component instance |

Replace `[email name]` with the actual name. The text after `✉️ Emailify MCP:` becomes the Emailify email name and must not be empty.

Do not detach instances, recreate components as raw layers, or place text, images, groups, or other non-Emailify nodes directly inside the email frame. Make content changes through instance overrides so design-system updates can still flow through every assembled email.

## Subject line and preheader

Create a separate top-level sibling frame for email metadata. Its email name must exactly match the email frame:

| Property | Required value |
| --- | --- |
| Frame name | `✉️ Emailify MCP Metadata: [same email name]` |
| Subject layer | A TEXT layer named `Subject Line` containing only the subject |
| Preheader layer | A TEXT layer named `Preheader Text` containing only the preheader |

Keep this metadata frame outside the email frame. Do not add labels, prefixes, notes, or alternative copy to the text values.

Emailify imports each field independently when the plugin opens or refreshes. Unchanged canvas metadata does not overwrite later manual edits made inside Emailify. If the agent changes a metadata value on the canvas, Emailify imports that changed field on the next refresh.

## Editing an existing email

When updating an email that already follows this contract:

- Modify existing linked instances in place whenever possible.
- Add or reorder only linked Emailify section, wrapper, or hero instances.
- Preserve the email frame name and vertical auto-layout structure.
- Preserve existing component links and instance overrides unless the brief explicitly changes them.
- Never change, hide, or remove a locked layer or a layer whose name begins with `🔒`.
- Preserve existing links unless the brief provides an exact replacement URL.
- Update the matching metadata frame when the subject line or preheader changes.

## Adoption and validation

After the agent finishes, open or refresh Emailify. Emailify validates the candidate frame before applying its normal `mj-body` metadata and importing matching subject and preheader values.

Emailify rejects the frame if it is nested, empty, not vertically arranged, contains detached components, contains raw direct children, or includes component instances that are not valid Emailify section, wrapper, or hero roots. Rejection is intentional: ordinary Figma layouts should never be converted into Emailify emails by accident.

## Troubleshooting

| Problem | Check |
| --- | --- |
| Email is not recognized | Confirm the exact `✉️ Emailify MCP:` name, top-level position, vertical auto layout, and linked direct-child instances. |
| Subject or preheader is missing | Confirm the metadata frame uses the same email name and the text layers are named exactly `Subject Line` and `Preheader Text`. |
| A component is no longer linked | Replace the detached or rebuilt layers with an instance of the original Emailify main component. |
| Legal or fixed content changed | Lock the layer or prefix its name with `🔒`, then restore the approved content in the main component. |
| A manual Emailify value did not change | Edit the corresponding metadata text on the canvas, then refresh Emailify again. |

When Figma write tools are unavailable, use the validated JSON import workflow described in [Creating emails with AI Designer](/emailify/design/ai-designer).