VYG Docs
Guides for brand teams

Email broadcasts

Schedule, change and measure email broadcasts from your AI assistant.

A broadcast sends one live email template to an email audience, once or on a repeating schedule. Claude can list your broadcasts, schedule new ones, change paused ones, pause and resume them, test variants and report how your email is doing. The tools are email_broadcasts (reads) and manage_email_broadcast (changes).

Email must be enabled

Broadcasts need the beta:email-channel feature (Beta features) and a sign-in with your own VYG login; they do not work with an API key. Without email, Claude does not see these tools and every call is refused.

Reading broadcasts

  • list shows each broadcast with its state (scheduled, paused or sent), audience, template and schedule.
  • get adds how many emails it produced by status: queued, sent, delivered, bounced, complained, failed and suppressed. If a scheduled send could not finish, retry_note says it is being retried and since when. A send that still cannot finish after 24 hours (or one repeat interval, if shorter) is stopped, the recipients it had not emailed are marked failed, and last_run_error says why. A repeating broadcast then carries on with its next send.
  • variants lists its A/B variants, their share of traffic and the running test.
  • audiences lists the email audiences a broadcast can send to. These are your email audiences, not the customer segments of the segments tool.
  • drafts lists the drafts awaiting or past admin review: the campaigns drafted with AI in the VYG app and the broadcasts saved with create and draft: true. Pass status (for example awaiting_approval) to see only those, or run_id for one draft and the steps taken.

Scheduling and changing broadcasts

ActionWhat it doesConfirmation
createSchedules a live template to an audience, once (send_at) or every every_hours from first_send_at.confirm_send: true, or draft: true (see below)
updateChanges the name, audience, template, sending domain, schedule or send-time optimization of a paused broadcast that has not sent. It stays paused.None; nothing is sent
pauseStops sending at once, including a send in progress.None
resumeSchedules a paused broadcast again, optionally at a new send_at.confirm_send: true
cancelDeletes a paused broadcast that never sent. A broadcast that has sent stays paused so its results remain.confirm: true
add_variantAdds a variant template to test against the broadcast's own template. Brand admins only.confirm_live_change: true on a scheduled broadcast

Scheduling and resuming email real recipients, so Claude reviews the broadcast with you and asks before it passes confirm_send. As in the VYG app, only a brand admin can schedule or resume a broadcast. Adding a variant test also needs a brand admin, whether the broadcast is paused or scheduled. If you are not a brand admin, those calls are refused with insufficient_scope and nothing changes; Claude offers to save the broadcast with draft: true instead, for a brand admin to approve. Email broadcasts are paused, resumed and changed only with manage_email_broadcast; manage_campaign refuses them. Only subscribed recipients are mailed, unsubscribed and suppressed addresses are skipped, and daily warm-up limits apply. Sending needs a live template, a verified sending domain, your business address and an active VYG subscription.

Send-time optimization. On a one-time broadcast, optimize_send_time sends each recipient at their best hour, learned from their opens and clicks (or your brand's), within window_hours after send_at (default 24). holdout_pct of recipients (default 10) are sent at send_at so the lift can be measured.

Variant tests. add_variant adds another live template to the broadcast's email. With auto_winner, only sample_pct of the audience (default 20) gets the test; the winner is picked by a two-proportion z-test on metric (open rate by default) at min_confidence (default 0.95), or the leader after timeout_hours (default 4), and the rest of the audience gets the winner.

Drafts need an admin

create with draft: true saves the broadcast paused for review and puts it in the VYG app's Draft with AI panel (Campaigns), next to the drafts the app's AI makes. Any brand user can save a draft this way. Only a brand admin approves or rejects a draft there; approving schedules it. Until then Claude can read the draft but cannot approve, update, resume, cancel or add a variant to it, and those calls are refused with a conflict.

update only changes a broadcast that has not changed since Claude read it. If it was resumed, sent or edited in between, the change is refused with a conflict and Claude reads it again first.

Email performance

Two stats keys report on email:

  • email.deliverability: sends by status with delivery, bounce and complaint rates over the last 7 days, whether your brand is still warming up, and any alarm that would pause sending. Pass one broadcast id in campaign_ids to scope it to that broadcast.
  • email.scorecard: email-attributed revenue (7-day click, 1-day open), revenue per send, in-email interactions, the send-time optimization lift against its holdout and the auto-winner variant tests, for the period you ask about.

Example questions

  • "Which email broadcasts are scheduled for next week?"
  • "Schedule the October restock template to the VIP audience for Friday 10am, with send-time optimization."
  • "Pause the restock broadcast and move it to Monday 9am."
  • "Test the new subject line against the current one on that broadcast and pick the winner automatically."
  • "How is our email deliverability, and how much revenue did email bring in this month?"
  • "Which AI drafts are waiting for approval?"

On this page