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 without loading the surrounding documentation interface.

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:

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 vertical auto-layout frame on the page or inside Figma sections named exactly "✉️ Emailify MCP: [email name]" and include at least one linked Emailify section, wrapper, hero, or code-only custom-code instance. Ordinary images and frame layers may also be direct children and export as images. Never detach Emailify instances. Create a separate sibling frame in the same page or section 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	Directly on the Figma page or inside Figma sections; never inside an ordinary frame or group
Layout	Vertical auto layout
Direct children	Linked Emailify component instances, optionally mixed with ordinary exportable visual layers
Allowed Emailify roots	mj-section, mj-wrapper, or mj-hero; custom-code instances containing only Emailify Custom Code text layers
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 Emailify instances or recreate their contents as raw layers. Make component content changes through instance overrides so design-system updates can still flow through every assembled email. Ordinary images, frames, groups, and other visual layers may be placed directly inside the email frame; Emailify exports these as images rather than editable email content.

Subject line and preheader

Create a separate sibling frame in the same page or section 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.
• Keep Emailify components linked when adding or reordering them. Ordinary visual layers may coexist with them and export as images.
• 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 inside an ordinary frame or group, empty, not vertically arranged, contains a layer that cannot be exported, or lacks any linked Emailify section, wrapper, hero, or code-only custom-code component. 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, page or section position, vertical auto layout, and at least one linked Emailify direct-child instance.
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.

Custom-code components may sit directly between email sections, for example to open and close conditional template logic. Both the main component and its instance must contain one or more Custom Code text layers only. Empty components, nested frames, ordinary text, and mixed visual content do not qualify. Keep these components linked to their masters.

Figma sections may contain your email frames, including nested sections. Keep each metadata frame alongside its email in the same section where possible. Emailify prefers matching metadata in the same container; existing matching metadata elsewhere on the page remains supported. Ordinary frames and groups are not email containers.