Copilot — your in-app AI operator

Copilot is more than chat. It can read your reports + billing, draft campaigns + automations + templates, build segments from plain English, and act on your account when you give the green light. This page documents every tool it can call + how to keep it on-rails.

What can I ask?

Open the Copilot drawer (the floating button on the bottom-right, or Cmd / Ctrl + K) and type. Examples that work today:

"Show me last month's campaign report" → calls campaign_report_detail
"How much of my plan have I used?" → calls plan_quota_usage
"What's my next bill?" → calls billing_status
"Draft a campaign for this week's promo and use the welcome template" → calls draft_campaign_body + create_campaign_draft
"Build a segment of subscribers who opened in the last 30 days but not the last 7" → calls suggest_segment_rules + create_segment
"Save a template for cart abandonment" → calls create_template_from_prompt
"Create an automation for welcome emails" → calls create_automation_draft
"Send campaign #142 now" → calls send_campaign_now (asks for confirmation)

Two-tier safety model

Admin guardrails — set under Admin → AI training. Persona, on-topic scope, refusal strictness, forbidden topics, and the per-tool authorisation matrix.
Per-action confirmation — every destructive tool (sends, activations, deletes) routes through an in-chat confirm card. The customer sees what's about to happen and clicks Run before anything mutates state.

Tool catalogue

Read-only intelligence

Auto-runs when the question requires actual account data. No confirmation, no destructive risk.

Tool	Returns
`list_recent_campaigns`	Recent campaigns with status + send dates.
`campaign_stats`	Opens / clicks / bounces for a single campaign.
`campaign_report_detail`	Deep report — delivery breakdown + top clicked URLs.
`find_subscriber`	Lookup by email.
`list_lists`	The customer's lists with subscriber counts.
`list_templates`	Customer templates + system templates.
`list_automations`	Automations with status + enrolment counts.
`preview_template`	Subject + plain-text snippet of a template.
`billing_status`	Subscription state, trial days left, next bill date.
`list_invoices`	Recent payments with amount + status.
`plan_quota_usage`	Sends-this-month + subscribers vs cap.
`suggest_subjects`	5 subject-line variants from a brief.
`suggest_segment_rules`	NL → segment-rule JSON (preview only).
`draft_campaign_body`	HTML + plain text from a brief (preview only).

Draft creation

Mutate state but never send mail / charge / contact subscribers. Result includes a URL the user can open to finish in the GUI.

Tool	What it does
`create_list`	New subscriber list.
`create_campaign_draft`	Campaign in `draft` status. No sends queued.
`create_template_from_prompt`	Generated HTML template, saved to the library.
`create_automation_draft`	Automation row in `draft`. Canvas filled in the GUI.
`add_subscribers`	Bulk-add addresses to a list (up to 500/call, deduped).
`create_segment`	Persist a segment from a rule JSON block.

Authorised execution

Each call surfaces a ConfirmCard in chat. The user clicks Run before anything happens.

Tool	What it does
`schedule_campaign`	Set send_at on a draft campaign.
`send_campaign_now`	Flip a draft to `pending` so the dispatcher sends it.
`pause_campaign`	Pause an in-flight send.
`update_campaign_draft`	Patch subject / from / body / preview on a draft.
`duplicate_campaign`	Clone a campaign into a new draft.
`start_automation`	Activate a draft/paused automation.
`pause_automation`	Pause an active automation.
`remove_subscriber`	Unsubscribe a single subscriber from a list.

What Copilot can NOT do in v1

Change plans, issue refunds, apply promo codes — money moves stay in the GUI.
Bulk-delete subscribers (more than one) — admin-only via the dedicated UI.
Call external APIs (Slack, Twitter, etc.) — separate authorisation problem.
Touch other tenants' data — every tool scopes queries to the calling customer.

Configuring the assistant — admin view

Go to Admin → Settings → AI provider. Pick a provider (OpenAI / Anthropic / DeepSeek / Groq) and paste your API key.
Set the Copilot's display name + tagline. Email-marketing fun picks: Postie, Sendly, Quill, Inkly, Drafty, Stamper, Mailie.
Open Admin → AI training. Pick a template preset (Strict marketing-only / Friendly helper / Sales-focused / Support agent) or hand-craft the persona + guardrails.
Use the right-hand Try it pane to test the persona before publishing. Inspect the composed system prompt under the System prompt tab.
Toggle which tools the Copilot can use in the Tool authorisation card. Newly-shipped tools default to enabled — flip them off if your offering doesn't include that capability.
Hit Publish. Future Copilot conversations site-wide use the new policy immediately.

Audit trail

Every tool execution writes a row to the activity log under copilot.tool.<name> with the customer id, arguments, optional audit payload, error (if any), and duration. Search the admin Audit log to reconstruct exactly what the AI did, when, and for whom.

Adding your own tools

Drop a file under app/Domain/Copilot/Tools/ that extends CopilotTool. The service provider auto-discovers it on the next request — no registration line required. Override destructive() + summary() for ConfirmCard support.

// app/Domain/Copilot/Tools/MyCustomTool.php
namespace App\Domain\Copilot\Tools;

use App\Models\Customer;

class MyCustomTool extends CopilotTool
{
    public function name(): string { return 'my_custom_action'; }
    public function description(): string { return 'Does the thing.'; }
    public function parameters(): array {
        return ['type' => 'object', 'properties' => [
            'thing_id' => ['type' => 'integer'],
        ], 'required' => ['thing_id']];
    }
    public function destructive(): bool { return true; }
    public function summary(array $args): string { return "Do the thing to #{$args['thing_id']}."; }
    public function run(Customer $customer, array $args): array {
        // ...
        return ['ok' => true, 'audit' => [...]];
    }
}