Tools

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.

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.

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.

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.

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:

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.

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

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.

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

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

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.

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.

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.

Essentials

REST API

MCP

What costs credits

Emails

Campaigns

Audience

Brands

Analytics

Templates

ESP

`generate_email` in detail

Ask for good results

Troubleshooting

​What costs credits

​Emails

​Campaigns

​Audience

​Brands

​Analytics

​Templates

​ESP

​generate_email in detail

​Ask for good results

​Troubleshooting

What costs credits

Emails

Campaigns

Audience

Brands

Analytics

Templates

ESP

`generate_email` in detail

Ask for good results

Troubleshooting