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

# Tools

> All 46 MCP tools by area, what they cost, and how to get a good result from them.

The server exposes 46 tools across seven areas. You rarely need to name one. Describe what you want, and the assistant picks the tools and chains them. The names are here so you can recognise what it's doing and steer it when it picks the wrong one.

## What costs credits

Four tools spend **one credit** per call, the same as generating or AI-editing in the app:

| Tool | Does |
| - | - |
| `generate_email` | Writes a new email from a prompt |
| `edit_email` | Rewrites an existing email by instruction |
| `import_email_from_html` | Converts HTML into a new, editable email |
| `import_esp_template` | Imports a template from your connected ESP as a new email |

If the AI step itself fails, the credit is refunded. Everything else is free, including AI analysis such as `score_email`, `improve_email`, `apply_dark_mode`, `create_segment`, and `import_brand`. Every call, free or not, counts toward the per-minute call budget. See [Credits and limits](https://docs.alpacarelay.com/developers/limits.md).

## Emails

| Tool | Does |
| - | - |
| `generate_email` | Generate a complete email from a prompt and save it to your workspace. **1 credit** |
| `list_emails` | List your workspace's emails |
| `get_email` | Read an email's details and current content (MJML, subject, preheader) |
| `create_email` | Create an email, blank, from a template, or from MJML you supply |
| `set_email_content` | Replace an email's content with new MJML |
| `update_email` | Rename an email or change its description |
| `edit_email` | AI-edit an email by instruction (*"make the CTA stand out more"*). **1 credit** |
| `score_email` | Score the design and save the score, with recommendations |
| `improve_email` | Get detailed improvement suggestions. Changes nothing |
| `apply_dark_mode` | Add dark-mode styling and save it |
| `send_test_email` | Send one test to **your own** verified address, from a connected sending account |
| `import_email_from_html` | Turn HTML into a new, editable email. **1 credit** |
| `delete_email` | Permanently delete an email |

`edit_email` saves only if nobody changed the email while it worked. If you or a teammate saved it in the editor meanwhile, your save is kept, the edit is discarded, the credit is refunded, and the assistant is told to read the email again.

## Campaigns

| Tool | Does |
| - | - |
| `create_campaign` | Create a draft campaign |
| `list_campaigns` | List campaigns |
| `get_campaign_state` | What's set, what's missing, and whether it's ready to send |
| `list_sending_accounts` | Your connected senders and whether each is verified |
| `list_segments` | Your saved audience segments |
| `preview_audience` | Count a segment or a contact search before you target it |
| `select_email` | Put an email's design on the campaign |
| `set_subject` | Set the subject line and preview text |
| `set_sender` | Choose a verified sending account, with optional From name and Reply-to |
| `set_recipients` | Target a segment, or a fixed list from a search (up to 5,000 contacts) |
| `set_send_now` | Mark the campaign "send now". **Doesn't send** |
| `set_schedule` | Propose a send time. The campaign stays a draft |

These tools work only on **draft** campaigns. None of them sends anything. When `get_campaign_state` says the campaign is ready, open it in the app to send it or confirm the schedule.

> [!TIP]
>
> To target more than 5,000 contacts, have the assistant create a segment with `create_segment` and target that instead. A segment has no size limit, and it's evaluated at send time, so contacts who join later are included.

## Audience

| Tool | Does |
| - | - |
| `list_contacts` | List contacts |
| `add_contacts` | Add or update contacts by email address |
| `import_contacts` | Bulk-import many contacts in one call, recorded as a single import |
| `create_segment` | Create a named segment from a plain-English description (*"customers who ordered in the last 30 days"*) |
| `count_segment` | How many contacts a segment matches right now |

## Brands

| Tool | Does |
| - | - |
| `list_brands` | List your brands |
| `get_brand` | A brand's colors, fonts, and tone |
| `create_brand` | Create a brand |
| `import_brand` | Extract a brand from a website and save it |

## Analytics

All read-only. The summary, series, and campaign-table tools take a number of days to look back over.

| Tool | Does |
| - | - |
| `get_analytics_summary` | Totals across the workspace |
| `get_analytics_series` | Day-by-day figures |
| `get_campaign_analytics` | One row per campaign |
| `get_campaign_stats` | One campaign in detail |

## Templates

| Tool | Does |
| - | - |
| `list_system_templates` | Browse the built-in template gallery |
| `get_template` | Read one template |

To start from a template, have the assistant pass its ID to `create_email`.

## ESP

These work only after you've connected an ESP in the app. Otherwise they reply that the provider isn't connected. Connecting stays a human step.

| Tool | Does |
| - | - |
| `esp_status` | Which ESPs are connected |
| `list_esp_templates` | Templates in your ESP that can be imported |
| `get_esp_links` | Where an email has been published |
| `sync_email_to_esp` | Publish an email as a template in your ESP. **Doesn't send mail** |
| `import_esp_template` | Import an ESP template as a new email. **1 credit** |
| `unlink_email_from_esp` | Detach an email from its ESP template |

## `generate_email` in detail

| Input | Required | Notes |
| - | - | - |
| `prompt` | Yes | What the email should be about |
| `branding_url` | No | A website to pull brand colors and style from |

It returns two blocks: the finished email as ready-to-send **HTML**, and a metadata block with `email_id`, `subject`, `preheader`, `score`, `subject_variants`, and `dark_mode`. The email is saved in your workspace, so the assistant can carry on with `edit_email`, `score_email`, or `select_email` using that `email_id`.

> [!NOTE]
>
> `generate_email` doesn't take a `format`. For the editable MJML source, follow up with `get_email`.

Generation takes roughly **one to three minutes**. The server sends progress pings throughout so your client doesn't drop the connection. Expect a pause, not a hang.

## Ask for good results

The same things that make a good prompt in the app make a good one here: **who it's going to**, **what you want them to do**, and **the tone**. A brand handles the look.

```text theme={null}
Generate an email for customers who haven't ordered in 90 days.
Warm, not pushy, one clear button back to the store.
Use our styling from https://example.com
```

The assistant can chain the steps for you:

```text theme={null}
Make a spring launch email for our coffee subscription using our
"Main" brand, score it, fix anything under 80, then set up a draft
campaign to the "Subscribers" segment from hello@example.com.
```

> [!TIP]
>
> Detail in the first request beats a chain of regenerations. For small changes, ask for an edit (*"tighten the headline"*), not a new email. Both cost one credit, but an edit keeps everything you already liked. Asking for "a few variations" spends a credit on each one, so say how many you want.

## Troubleshooting

> [accordion] The assistant doesn't use the tools
>
> Mention AlpacaRelay or the tool by name, such as *"use generate\_email to…"*. Assistants sometimes write their own draft when the request sounds like ordinary writing.

> [accordion] "Too many tool calls: the limit is 60 a minute"
>
> The per-minute call budget is spent. The message says how many seconds to wait. Long agent loops over many contacts or emails hit this first, so ask for one bulk call (`import_contacts`) instead of many small ones.

> [accordion] "Too many concurrent generations"
>
> Three generations run at once per workspace, counted across every key and sign-in. A fourth is refused until one finishes, and extra keys don't raise the limit. Only `generate_email` counts toward it.

> [accordion] The assistant gives up while waiting
>
> Generation can take minutes. If your client has a configurable tool timeout, raise it to at least six minutes. If it gives up anyway, the email usually still finishes and appears in your workspace, so check `list_emails` before asking again.

> [accordion] A campaign tool refuses to change the campaign
>
> It has left draft, because it was sent or scheduled in the app. Create a new campaign, or edit this one in the app.

> [accordion] It says you're out of credits
>
> Top up under **Settings** → **Billing & usage**. Credits are shared with the app and the REST API. There's no separate API allowance.


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