> ## Documentation Index
> Fetch the complete documentation index at: https://help.emaillove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the Builder from an AI agent

> Connect Claude, ChatGPT, Cursor, Claude Code or Codex to Email Love Builder. Your agent can read your design systems, build and edit emails, check, translate, export and push them.

Email Love Builder has 51 tools an AI agent can use. With them, your agent can build an email from your design system from start to finish, the same way you would in the Builder.

There are three ways to connect:

| | How it signs in | Best for |
| - | - | - |
| **[chat.emaillove.com](#connect-with-your-email-love-sign-in)** (recommended) | Your Email Love account. No key to paste. | Claude, ChatGPT, Cursor, Claude Code, Codex and other AI tools |
| **[The Builder's MCP server](#connect-with-a-builder-api-key)** | A Builder API key | Scripts and automation, and teams that sign in with SSO or two-factor sign-in |
| **[The REST API](#use-the-rest-api)** | A Builder API key | Your own code |

## How it works

* **It works as you.** The tools have your role in the workspace, as in the app. An API key never has more rights than the person who made it.
* **Teammates' changes are kept.** Every edit includes `baseRevision`, the email revision the agent last read. Changes teammates made since then to other parts of the email are merged in. If two changes touch the same part, the agent is told what changed, reads the email again and retries. People who have the email open see the changes live.
* **Sign-off still applies.** An email that needs sign-off can't be exported or pushed until a person approves it.
* **Your plan's limits still apply.** Exports and pushes count the same way they do in the app. The Assistant and AI translation use your plan's AI credits.
* **Some things stay with people.** Approving an email and deleting an email are not tools. A person does those in the Builder.

## What your agent can do

You don't need to name the tools. Ask in plain words, and the agent picks them. On chat.emaillove.com, every Builder tool name starts with `builder_`, for example `builder_open_email`. On the Builder's own MCP server and in the REST API, the names have no prefix.

### Brand and library

| Tool | What it does |
| - | - |
| `list_workspaces` | Lists the workspaces you can work in. |
| `list_design_systems` | Lists a workspace's design systems. |
| `get_design_system` | Reads one design system in full: its brand styles and every component with its fields. |
| `get_brand_styles` | Reads the brand styles: colors, fonts, type sizes, button styles, email width and logos. |
| `list_components` | Lists the components a design system offers. |
| `get_component` | Reads one component: its fields, the parts you can show or hide, and how it can be styled. |
| `list_templates` | Lists the templates you can start an email from. |
| `list_merge_tags` | Lists the workspace's merge tags. |
| `list_conditions` | Lists the workspace's saved conditions for dynamic content. |
| `list_images` | Lists the pictures in the image library, newest first. |
| `upload_image_from_url` | Adds a picture to the image library from a public link. |

### Campaigns

| Tool | What it does |
| - | - |
| `list_campaigns` | Lists campaigns and the folders they sit in. |
| `create_campaign` | Creates an empty campaign. |
| `update_campaign` | Renames a campaign or changes its description. |
| `create_campaign_folder` | Creates a folder for campaigns. |
| `move_campaign_to_folder` | Moves a campaign into a folder, or out of one. |

### Emails

| Tool | What it does |
| - | - |
| `open_email` | Picks up work on one email, from its ID or its Builder link: content, review status, brand styles and components in one go. |
| `list_emails` | Lists the emails in a campaign or design system, or the ones edited most recently. |
| `get_email` | Reads one email: its details, its revision and its sections in order. |
| `create_email` | Creates a draft email from a template, from sections you list, or empty. |
| `set_email_details` | Sets an email's name, subject line or preheader. |
| `update_email_fields` | The older way to edit: saves the whole email at once. MCP only. |
| `duplicate_email` | Makes a copy of an email in the same campaign. |
| `move_email_to_campaign` | Moves an email to another campaign. |

### Sections

| Tool | What it does |
| - | - |
| `add_section` | Adds a section from one of your components. |
| `move_section` | Moves a section to another place in the email. |
| `remove_section` | Takes a section out of the email. |
| `duplicate_section` | Copies a section, straight after it. |
| `set_section_fields` | Changes a section's text, links, images, colors and options. |
| `set_section_parts` | Shows or hides a section's optional parts, such as its image or button. |
| `set_section_style` | Styles a section: background, padding, mobile stacking, column widths, and desktop-only or phone-only. |
| `set_section_condition` | Chooses who sees a section, with a saved condition or your own platform code. |
| `apply_email_edits` | Makes several edits in one save, including the edits the Assistant suggests. |

### Preview and checks

| Tool | What it does |
| - | - |
| `preview_email` | Shows the email as the editor's preview does, in light or dark mode and in any of its languages. |
| `check_email` | Runs the editor's checks: required fields, links, images, merge tags, unsubscribe link, size and your team's own rules. |

### Review

| Tool | What it does |
| - | - |
| `get_review` | Reads an email's review status, approval steps and comments. |
| `add_comment` | Comments on an email or one of its sections, or replies to a comment. |
| `resolve_comment` | Resolves a comment, or opens it again. |
| `request_signoff` | Sends the email for review and returns the review link. |

### Translations

| Tool | What it does |
| - | - |
| `list_languages` | Lists an email's languages and how far along each is. |
| `get_translation` | Reads every piece of text in one language: the original, the translation and whether it's missing or out of date. |
| `set_translation_strings` | Saves translated text. |
| `add_language` | Adds a language to an email. |
| `translate_with_ai` | Fills in missing and outdated text with AI, using your brand's translation guidance. |

### Export and send

| Tool | What it does |
| - | - |
| `list_destinations` | Lists the sending platforms your workspace has connected. |
| `export_email` | Exports the finished HTML for any sending platform, or an image or a hosted web page of the email. |
| `push_to_esp` | Pushes the email to a connected sending platform. |
| `send_test_email` | Sends a test to up to 10 inboxes. |

### Assistant

| Tool | What it does |
| - | - |
| `ask_assistant` | Asks the Assistant to change an email in words. It suggests edits, and the agent applies the ones you want. |
| `create_email_from_brief` | Has the Assistant write a new draft email from a brief, using your components and brand guidance. |
| `suggest_subject_lines` | Suggests up to three subject lines with preheaders. |

## Connect with your Email Love sign-in

This is the easiest way, through chat.emaillove.com. You add one URL to your AI tool and sign in with your Email Love account. The same connection also has the [Email Love MCP](https://help.emaillove.com/plugin/ai/email-inspiration-mcp.md) research tools for the library of real marketing emails.

### Before you start

You need:

* An Email Love Builder account.
* Your Builder account connected to your Email Love account. In the Builder, open **Edit Profile** from the menu under your name, then click **Connect Email Love**. If you sign in to the Builder with Email Love, it's already connected.

The server URL is always:

```text theme={null}
https://chat.emaillove.com/mcp
```

Already connected to the Email Love MCP for research? There's nothing to add. Start a new chat and the Builder tools are there.

> [!NOTE]
>
> If your organisation signs in to the Builder with SSO or asks for two-factor sign-in, or you've turned on two-factor sign-in yourself, chat.emaillove.com can't reach your Builder account. [Connect with a Builder API key](#connect-with-a-builder-api-key) instead.

### Add it to your AI tool

> [tab] Claude
>
> Works in Claude.ai, the Claude desktop app and Cowork.
>
> 1. Open **Customize → Connectors**, click **+ Add**, then **Add custom connector**.
> 2. Name it **Email Love** and paste the server URL.
> 3. Sign in to Email Love and click **Allow**.
> 4. In a new chat, open **+ → Connectors** and turn on **Email Love**.

> [tab] ChatGPT
>
> 1. Open **Plugins** in the sidebar, click **+**, then **Add custom MCP server**.
> 2. Name it **Email Love**, paste the server URL, and choose **OAuth**.
> 3. Sign in to Email Love and click **Allow**.
> 4. In a new chat, type **@** and choose **Email Love**.

> [tab] Cursor
>
> 1. Add this to `~/.cursor/mcp.json`, save it, and restart Cursor:
>
>    ```json theme={null}
>    {
>      "mcpServers": {
>        "email-love": { "url": "https://chat.emaillove.com/mcp" }
>      }
>    }
>    ```
>
> 2. Cursor asks you to sign in the first time a tool runs. Sign in to Email Love and click **Allow**.

> [tab] Claude Code
>
> 1. Run this once in your terminal:
>
>    ```bash theme={null}
>    claude mcp add --scope user --transport http email-love https://chat.emaillove.com/mcp
>    ```
>
> 2. In Claude Code, run `/mcp`, choose **email-love**, and sign in to Email Love in the browser.

> [tab] Codex
>
> 1. Run these in your terminal:
>
>    ```bash theme={null}
>    codex mcp add email-love --url https://chat.emaillove.com/mcp
>    codex mcp login email-love
>    ```
>
> 2. Sign in to Email Love in the browser, then start a new Codex task so the tools load.

### Check that it works

Ask your agent to list your Builder workspaces. It runs `builder_list_workspaces` and shows your workspaces.

If you're in more than one workspace, every Builder tool takes an optional `workspaceId`. Leave it out to use your usual workspace.

## Connect with a Builder API key

The Builder has its own MCP server. It takes a Builder API key instead of a sign-in. Use it for scripts and automation, or if your organisation signs in with SSO or two-factor sign-in.

### Create a key

Create a key in the Builder under **Settings › API keys**. Copy it straight away: it's shown once. Keys start with `ef_`.

A key works in one workspace and never has more rights than the person who made it. Pick its access level when you create it:

| Access | What the agent can do |
| - | - |
| **Read only** | Look at brand styles, components, templates, campaigns, emails, previews, checks, comments, languages and the image library. |
| **Draft** | Also create and edit emails and campaigns, add and style sections, set dynamic content, add images, comment, write translations and ask for sign-off. |
| **Full** | Everything the key's person can do: also export, push to a sending platform, send tests, add languages, translate with AI and use the Assistant. |

The agent only sees the tools its key allows. A Read only key can't call any tool that changes something.

### Connect your AI tool

| Setting | Value |
| - | - |
| Server URL | `https://app.emaillove.com/api/mcp` |
| Transport | Streamable HTTP |
| Header | `Authorization: Bearer ef_your_key` |

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http email-love-builder https://app.emaillove.com/api/mcp \
>   --header "Authorization: Bearer ef_your_key"
> ```

> [tab] Cursor
>
> Add this to `~/.cursor/mcp.json` in your home folder, not a project's, so the key never ends up in a repository:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "email-love-builder": {
>       "url": "https://app.emaillove.com/api/mcp",
>       "headers": { "Authorization": "Bearer ef_your_key" }
>     }
>   }
> }
> ```

> [tab] Codex
>
> Add this to `~/.codex/config.toml`, and set `EMAIL_LOVE_BUILDER_KEY` to your key in your shell:
>
> ```toml theme={null}
> [mcp_servers.email-love-builder]
> url = "https://app.emaillove.com/api/mcp"
> bearer_token_env_var = "EMAIL_LOVE_BUILDER_KEY"
> ```

Here the tool names have no prefix: `list_workspaces`, `open_email` and so on.

## Use the REST API

Every tool except `update_email_fields` is also a REST call, with the same name and arguments. That's 50 calls.

* **Base URL:** `https://app.emaillove.com/api/v1`
* **Sign-in:** a Builder API key, as `Authorization: Bearer ef_your_key`
* **Reference:** the OpenAPI 3.1 description is at [app.emaillove.com/api/v1/openapi.json](https://app.emaillove.com/api/v1/openapi.json), with no key needed. Load it into Postman, an SDK generator or an AI tool. The Builder's own reference page is at [app.emaillove.com/docs/api](https://app.emaillove.com/docs/api).

```bash theme={null}
curl "https://app.emaillove.com/api/v1/design-systems" \
  -H "Authorization: Bearer ef_your_key"

curl -X POST "https://app.emaillove.com/api/v1/emails/123/sections" \
  -H "Authorization: Bearer ef_your_key" -H "Content-Type: application/json" \
  -d '{"baseRevision": 4, "component": "ueds_hero_image", "fields": {"headline": "Autumn is here"}}'
```

Errors come back as JSON, `{ "error": "…", "code": "…" }`:

| Status and code | What it means |
| - | - |
| `403` `API_KEY_SCOPE` | The key's access level is too low for this call. The answer says which level it needs. |
| `409` `EMAIL_OPS_CONFLICT` | Someone changed the same part of the email. Read the email again and retry. |
| `429` `LIMIT_REACHED` | Your plan's limit for this is used up. |

## Example requests

Ask your agent things like:

* "Open the Northwind Outfitters design system and tell me which components it has."
* "Create a spring sale email for Northwind Outfitters from the Seasonal template. Use the subject line 'Trail season starts now'."
* "Move the product grid above the hero and make the button say Shop the sale."
* "Check the email and fix anything that would stop it exporting."
* "Add French and translate it."
* "Send me a test, then push it to Klaviyo."

## Common problems

**"Connect your Email Love Builder account first"**

Your Email Love account isn't connected to a Builder account yet. Open the link in the reply, or in the Builder open **Edit Profile** and click **Connect Email Love**. Then try again.

**"Your organisation signs in with SSO" or "asks for two-factor sign-in"**

chat.emaillove.com can't reach Builder accounts that sign in that way. [Connect with a Builder API key](#connect-with-a-builder-api-key).

**"This workspace doesn't have Email Love Builder for your account yet"**

The workspace owner can start the Builder for the workspace, or give you access to it. The library tools still work.

**"Builder tools need you to sign in with your Email Love account"**

You connected chat.emaillove.com with an Email Love API key. That key only reaches the library. Remove the connection and add it again with sign-in.

**"This API key is Read only"**

The key's access level is too low for that tool. Create a key with the access you need and update your AI tool. You can't change an existing key's access.

**The Builder tools don't appear**

Start a new chat or task: tools load when a conversation starts. In Claude Code, run `/mcp`. In the Claude desktop app, quit it completely and reopen it.

## Related

* [Email Love MCP](https://help.emaillove.com/plugin/ai/email-inspiration-mcp.md): research real marketing emails from your AI tool, over the same connection.
* [Build with the Figma MCP](https://help.emaillove.com/plugin/ai/agents-in-figma.md): build emails on your Figma canvas instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.