VYG Docs
Tools

Email tools

Set up and run the email channel from an AI assistant, from sending domain to scheduled broadcasts.

The email tools let an assistant run your email channel end to end: connect a sending domain, write templates, build automated emails such as abandoned checkout, schedule broadcasts to a segment and watch deliverability.

The email tools are served on https://agents-mcp.vyg.app/mcp to LiveRecover staff and agents, who sign in at agent.vyg.app. The brand MCP server at https://api.vyg.app/mcp does not serve them.

# Staff or LiveRecover agent (sign in at agent.vyg.app)
claude mcp add --transport http vyg-email https://agents-mcp.vyg.app/mcp

Email must be enabled

The email tools appear only when email is enabled for your brand. Without it, the server lists none of them and refuses every call. Ask your VYG account manager to enable email.

Your assistant signs you in the first time it connects. Every tool works on the brand you signed in to; no tool takes a brand id. Lists return up to 25 items by default and at most 100, with a next_cursor to pass back as cursor for the next page.

A full setup, step by step

  1. Connect a sending domain. email_domain_add returns the DNS records to publish. After publishing them, email_domain_recheck confirms the domain. Use a subdomain such as mail.yourstore.com.
  2. Add your business address. Every marketing email must show a postal address. email_brand_address_get shows what is on file and email_brand_address_set saves it. You can also set it in VYG under Settings → Email → Business address.
  3. Write a template. email_template_create saves it live as soon as it passes the checks below. email_template_preview shows it with sample data and email_template_test_send sends one copy to your own inbox. For interactive blocks, email_block_contracts_list → email_template_validate → email_template_preview_tiers → email_template_test_send_interactive.
  4. Build the automation. email_flow_create with the checkout/abandoned trigger and an Email step (or a Resend step) creates the flow paused. email_flow_activate starts it.
  5. Watch results. email_send_list, email_deliverability_stats and email_sending_status.
  6. Broadcast to a segment. email_segment_create, then email_broadcast_create with a send time. email_broadcast_pause stops it at any time.
  7. Bring your own list. If your subscribers live in another email provider rather than Shopify, email_contact_import loads them with their consent (see below) so broadcasts reach them.

Example requests:

Connect mail.acme.com as our sending domain and tell me which DNS records to add.
Create an abandoned checkout email that lists the cart items with images, send me a test, then turn it on
one hour after checkout is abandoned.
Email everyone in the VIP segment our restock template next Tuesday at 9am New York time.

Templates

email_template_create and email_template_update run the same checks before saving. If a check fails nothing is saved and the assistant gets the list of problems to fix:

  • a subject and an HTML body;
  • an unsubscribe link whose address is {{unsubscribe}};
  • no <script> tags, on… event handlers or javascript: links;
  • an HTML body under 100 KB.

A missing postal address and unknown variables come back as warnings. Saved templates are live and can be used by flows and broadcasts right away. Templates follow the same rules whether they are saved here or in VYG under Settings → Email. Editing a template keeps its id, so everything that uses it picks up the change on its next send. The version number goes up when a live template changes. An edit that would overwrite someone else's newer save is refused, so the assistant reads the template again and retries. Pass expected_version to refuse the edit whenever the template is no longer at the version the assistant read. email_template_archive retires a template: anything still pointing at it stops sending until it uses a live template. Archived templates cannot be edited.

Variables

Write variables as {{name}} in the subject, body or plain text. email_template_variables_list returns this list to the assistant.

VariableFills in
{{contact.first_name}}Recipient's first name (blank when unknown)
{{contact.last_name}}Recipient's last name
{{contact.email}}Recipient's email address
{{event.checkout_url}}Link back to the abandoned checkout
{{event.shop_pay_checkout_url}}Shop Pay-prefilled checkout; cart.rebuild redirects here
{{event.cart_total}}Cart total with currency, such as $40.37
{{brand.name}}Your brand name
{{brand.support_email}}Your support email
{{brand.address}}Your postal address on one line; put it in the footer
{{brand.domain}}Your store domain
{{generated.unsubscribe_url}}One-click unsubscribe link, filled in per recipient
{{unsubscribe}}Same unsubscribe link
{{product.title}}Product title
{{product.variant_title}}Variant, such as size or color
{{product.price}}Item price with currency
{{product.image_url}}Product image from your synced catalog
{{product.product_url}}Product page, or the checkout link when there is none
{{block.body}}Slot inside a <vyg-block> shell the renderer fills
{{blocks.cart}}Abandoned-cart interactive block
{{blocks.subscription}}Subscription-management interactive block
{{blocks.custom_action}}One-click custom action block
{{blocks.review}}Tap-to-rate review block
{{blocks.form}}Multi-step form or quiz block
{{blocks.carousel}}Product or image carousel block

To repeat a block for every item in the cart, wrap it in {{#each products}}…{{/each}}. Inside the block the product.* variables refer to the current item. Outside a block they refer to the first item in the cart.

Interactive blocks

Agent-authored templates may drop a <vyg-block> tag into the HTML. email_block_contracts_list returns each block type's JSON Schema, an example config, the actions it may emit, and the webhook HMAC key for the signed-in brand (never the root secret).

List the block contracts, then draft a cart block with max_items 3, validate it, preview links/kinetic/AMP,
and send me an interactive test.

email_template_validate runs the same quality gates as save (including AMP4EMAIL) but writes nothing. An invalid cart config comes back as BLOCK_CONTRACT_INVALID with the zod path (max_items) and a line hint.

email_template_preview_tiers returns the links HTML, the kinetic HTML, and the AMP document for a sample recipient (pass recipient_context or accept the brand default). Tokens are not minted in preview.

email_template_test_send_interactive sends one copy to your own inbox with real action tokens flagged is_test. Taps run in dry-run: cart and subscription writes are simulated and the interaction row has meta.dry_run = true. It cannot send to anyone else.

The block tag, the three renderings (signed links, Apple Mail kinetic HTML, AMP), AMP registration and how a tap is authorized are on the Interactive email page.

Business address

Anti-spam law requires every marketing email to show the sender's postal address, which templates add with {{brand.address}}. email_flow_activate, email_broadcast_create and email_broadcast_resume refuse to go live until your brand has one.

email_brand_address_set takes line1 (street address), city and country, which are required, plus optional line2, region (state or province) and postal (postal or ZIP code). It replaces the whole address and returns the line that emails will show, such as 100 Main St, Austin, TX 78701, US. Every part is trimmed and must be plain text without < or >. If a part is missing or invalid, nothing is saved.

Automated flows

email_flow_create builds a flow with a trigger, an optional wait and one email step. The trigger is either a store event, trigger_event (checkout/abandoned or order/delivered, which need a connected Shopify store), or one of your Custom E-Com events, custom_event: { type }, such as hq_checkout_abandoned. Your own system sends those events to VYG. If two providers define the same event type, add provider. For a brand without Shopify, the error lists its custom event types.

The email step is one of:

  • Email step. Sends a live VYG template from a verified domain. Pass from_domain, or leave it out to use your first verified domain.
  • Resend step. Sends a template from your own Resend account. Pass the Resend template id, the from address and variable_mappings from each Resend variable to a data path such as contact.first_name or event.checkout_url. Resend must be connected in VYG.

New flows are saved paused. email_flow_activate checks that every Email step has a live template and a verified domain and that your brand has a postal address, then starts the flow; if something is missing it changes nothing and lists the problems. Starting a flow requires an active VYG subscription. email_flow_pause stops it. email_flow_update_node changes the template, domain or Resend settings, also on a running flow. email_flow_delete removes a paused flow or broadcast that has never sent anything. It stops for good at once and disappears from the email tools. In VYG it stays listed as paused, with [Deleted] before its name.

Message variants are optional. email_flow_variant_add adds another live template that competes with the step's own template, and better performers get more traffic over time. A step without variants sends its own template to everyone.

Segments and broadcasts

A segment is either a list of up to 5,000 addresses or a customer-data condition, and it always contains only your customers. email_broadcast_create sends a live template to a segment once at send_at, or repeatedly with first_send_at and every_hours (24 or more). Only subscribed recipients are mailed; unsubscribed and suppressed addresses are skipped. email_broadcast_pause stops a broadcast, including a send already in progress, and email_broadcast_resume restarts it, optionally at a new time.

Importing contacts

email_contact_import loads a list exported from another email provider, up to 200 contacts per call. Each row carries an email, an optional first_name, last_name, company and website, a consent of subscribed, unsubscribed or not_subscribed, and an optional consent_at (when the customer gave or withdrew consent). The call also takes a consent_source such as customer.io export 2026-10-26, recorded with every row. Only rows marked subscribed are mailed by broadcasts. A contact whose consent is already recorded here only changes when the row's consent_at is later than the recorded time, and an unsubscribe or bounce is never undone without one; such rows come back as skipped. Addresses are matched exactly on their lower-cased, trimmed form; a contact stored in mixed case by an old import is treated as not found. The result lists how many contacts were created, updated and skipped, and one error per rejected row (invalid or duplicate email). Repeating a call is safe: unchanged rows are skipped.

Monitoring

  • email_send_list: recent sends with recipient, status and the flow or broadcast that sent them. Test sends are left out unless include_tests is true.
  • email_deliverability_stats: delivery, bounce and complaint rates over the last 7 days, for the whole brand or one flow, plus any alarm that would pause sending.
  • email_sending_status: each domain's verification, its daily warm-up limit and whether sending is paused. New domains start with a small daily limit that grows as they warm up.
  • email_suppression_list: addresses that are never emailed, with the reason.
  • email_suppressions_import: load the unsubscribes, spam complaints and hard bounces exported from a previous email provider (for example Customer.io) so those addresses are never emailed. Up to 1,000 rows per call, each with email, reason (unsubscribe, complaint, bounce or manual), source and an optional occurred_at. Safe to repeat: an address that is already suppressed is left as it is and counted as already_suppressed. Returns added, already_suppressed, invalid and per-row errors.
  • email_catalog_status: whether your product catalog has synced, with product counts and the last error. Until the first sync completes, {{product.image_url}} is blank. The catalog refreshes automatically, and email_catalog_sync_request asks for a full sync sooner. The request is queued and runs within about 15 minutes. The current catalog stays in use until the new sync completes. A brand without a connected Shopify store has no catalog: both tools return applicable: false, and sending is not affected.

All email tools

ToolWhat it doesReads or changes
email_domain_listSending domains, status and DNS recordsReads only
email_domain_addConnect a domain and get its DNS recordsMakes changes
email_domain_recheckCheck DNS and update the domain statusMakes changes
email_domain_amp_requestRecord Google/Yahoo AMP registration form refsMakes changes
email_brand_address_getYour business postal addressReads only
email_brand_address_setSave your business postal addressMakes changes
email_template_variables_listSupported variables and what they fill inReads only
email_block_contracts_listBlock JSON Schema, example config, webhook HMAC keyReads only
email_template_listTemplates with status and versionReads only
email_template_getOne template in fullReads only
email_template_createSave a new live templateMakes changes
email_template_updateEdit a template in placeMakes changes
email_template_archiveRetire a templateMakes changes
email_template_previewRender with sample data, without sendingReads only
email_template_preview_tiersLinks, kinetic, and AMP renders of a templateReads only
email_template_validateQuality gates + AMP, no save, codes with line hintsReads only
email_template_test_sendSend one copy to your own email addressSends an email to you
email_template_test_send_interactiveInteractive test send with dry-run action tokensSends an email to you
email_flow_createBuild a paused flow with an Email or Resend stepMakes changes
email_flow_listFlows that send emailReads only
email_flow_getOne flow and its email stepsReads only
email_flow_update_nodeChange an email stepMakes changes
email_flow_activateStart a flowMakes changes
email_flow_pausePause a flowMakes changes
email_flow_deleteDelete a paused flow or broadcast that never sentMakes changes
email_flow_variant_listVariants on an Email stepReads only
email_flow_variant_addAdd a variant to an Email stepMakes changes
email_contact_importImport contacts with their marketing consentMakes changes
email_segment_createCreate a segmentMakes changes
email_segment_listSegmentsReads only
email_segment_bind_flowNote that a flow uses a segment (does not send)Makes changes
email_segment_deleteDelete a segmentMakes changes
email_broadcast_createSchedule a broadcastMakes changes
email_broadcast_listBroadcasts and their stateReads only
email_broadcast_getOne broadcast with send countsReads only
email_broadcast_pausePause a broadcastMakes changes
email_broadcast_resumeResume or reschedule a broadcastMakes changes
email_send_listRecent sendsReads only
email_deliverability_statsDelivery, bounce and complaint ratesReads only
email_sending_statusDomains, warm-up limits and pausesReads only
email_suppression_listAddresses that are never emailedReads only
email_suppressions_importImport opt-outs from a previous email providerMakes changes
email_catalog_statusProduct catalog sync statusReads only
email_catalog_sync_requestQueue a full product catalog syncMakes changes
email_interaction_listIn-email shopper actions (paginated, masked)Reads only
email_scorecard_getAttributed revenue, interactions, per-variant armsReads only

Ask your assistant to show what it is about to change and to wait for your confirmation before it runs a tool that makes changes, especially email_flow_activate and email_broadcast_create, which send to real customers.

Next steps

On this page