Nova — AI Email Employee

# Nova — AI Email Employee · Complete Setup & API Reference Build "Nova" — an AI email employee inside ClawBuddy's OpsCenter. Nova sends personalized email sequences to lead lists, tracks every open/click/reply via Resend webhooks, manages campaigns with daily send limits, and provides full engagement analytics. --- ## Step 1: Run Database Migration Create Nova's 5 tables. Run this SQL migration against your Supabase project: **Tables created:** - `nova_templates` — email templates with {{variable}} support - `nova_sequences` — multi-step email flows with delays and conditions - `nova_campaigns` — campaign records linking sequences + templates + leads - `nova_emails` — individual email records with full lifecycle tracking - `nova_daily_metrics` — daily aggregated stats for analytics charts Each table has RLS policies, indexes, and real-time publication enabled. ```bash # From your project directory: supabase db push ``` Migration file: `supabase/migrations/20260228100000_nova_email_employee.sql` --- ## Step 2: Set Secrets ```bash supabase secrets set RESEND_API_KEY=re_your-resend-api-key ``` --- ## Step 3: Verify Sending Domain In the Resend dashboard: 1. Go to Domains → Add Domain 2. Add your sending domain (e.g., `yourdomain.com`) 3. Add the DNS records Resend provides (SPF, DKIM, DMARC) 4. Wait for verification (5-30 minutes) Your emails will send from `nova@yourdomain.com`. --- ## Step 4: Create the OpsCenter App ```json { "request_type": "ops", "action": "create_app", "name": "Nova", "description": "AI Email Employee — sequences, templates, and engagement analytics", "icon": "mail", "agent_name": "<agent_name>", "agent_emoji": "<agent_emoji>" } ``` Save the returned `app_id`. --- ## Step 5: Create Pages (6 tabs) ```json {"request_type": "ops", "action": "create_page", "app_id": "<app_id>", "name": "Dashboard", "sort_order": 1} ``` ```json {"request_type": "ops", "action": "create_page", "app_id": "<app_id>", "name": "Outbox", "sort_order": 2} ``` ```json {"request_type": "ops", "action": "create_page", "app_id": "<app_id>", "name": "Templates", "sort_order": 3} ``` ```json {"request_type": "ops", "action": "create_page", "app_id": "<app_id>", "name": "Sequences", "sort_order": 4} ``` ```json {"request_type": "ops", "action": "create_page", "app_id": "<app_id>", "name": "Campaigns", "sort_order": 5} ``` ```json {"request_type": "ops", "action": "create_page", "app_id": "<app_id>", "name": "Analytics", "sort_order": 6} ``` --- ## Step 6: Create Blocks (6 block types) ```json {"request_type": "ops", "action": "create_block", "page_id": "<dashboard_page_id>", "name": "Command Center", "block_type": "nova_dashboard", "config": {}} ``` ```json {"request_type": "ops", "action": "create_block", "page_id": "<outbox_page_id>", "name": "Outbox", "block_type": "nova_outbox", "config": {}} ``` ```json {"request_type": "ops", "action": "create_block", "page_id": "<templates_page_id>", "name": "Templates", "block_type": "nova_templates", "config": {}} ``` ```json {"request_type": "ops", "action": "create_block", "page_id": "<sequences_page_id>", "name": "Sequences", "block_type": "nova_sequences", "config": {}} ``` ```json {"request_type": "ops", "action": "create_block", "page_id": "<campaigns_page_id>", "name": "Campaigns", "block_type": "nova_campaigns", "config": {}} ``` ```json {"request_type": "ops", "action": "create_block", "page_id": "<analytics_page_id>", "name": "Analytics", "block_type": "nova_analytics", "config": {}} ``` --- ## Step 7: Configure Resend Webhook To receive real-time email events: 1. In Resend dashboard → Webhooks → Add Webhook 2. Set URL: `https://<your-supabase-ref>.supabase.co/functions/v1/report-webhook?endpoint=nova-events` 3. Select events: `email.delivered`, `email.opened`, `email.clicked`, `email.bounced`, `email.complained` The webhook handler: - Updates `nova_emails` status + timestamps - Updates `nova_campaigns` aggregate counters and rates - Updates `nova_daily_metrics` for analytics charts --- ## Data Schemas ### Template (`nova_templates`) ```json { "name": "Cold Outreach v2", "subject": "Quick question about {{company}}", "body_html": "<p>Hi {{name}},</p><p>I noticed {{company}} is scaling their AI operations...</p>", "body_text": "Hi {{name}}, I noticed {{company}} is scaling...", "variables": ["name", "company", "role"], "category": "outreach", "tags": ["cold", "ai", "enterprise"], "usage_count": 47, "avg_open_rate": 0.42, "avg_reply_rate": 0.12, "is_active": true } ``` ### Sequence (`nova_sequences`) ```json { "name": "3-Touch Enterprise Outreach", "description": "Initial contact → follow-up → breakup email", "status": "active", "steps": [ {"step": 1, "template_id": "<template_uuid>", "delay_days": 0, "condition": "none"}, {"step": 2, "template_id": "<followup_uuid>", "delay_days": 3, "condition": "no_reply"}, {"step": 3, "template_id": "<breakup_uuid>", "delay_days": 7, "condition": "no_reply"} ], "total_enrolled": 150, "active_count": 89, "completed_count": 45, "stopped_count": 16 } ``` ### Campaign (`nova_campaigns`) ```json { "name": "Q1 Enterprise Push", "status": "active", "sequence_id": "<sequence_uuid>", "template_id": "<template_uuid>", "from_address": "nova@yourdomain.com", "total_leads": 200, "emails_sent": 147, "emails_delivered": 142, "emails_opened": 63, "emails_clicked": 28, "emails_replied": 17, "emails_bounced": 5, "meetings_booked": 4, "open_rate": 0.44, "click_rate": 0.20, "reply_rate": 0.12, "send_limit_per_day": 50, "send_window_start": "09:00", "send_window_end": "17:00", "timezone": "America/Vancouver" } ``` ### Email (`nova_emails`) ```json { "resend_id": "re_abc123xyz", "campaign_id": "<campaign_uuid>", "template_id": "<template_uuid>", "from_address": "nova@yourdomain.com", "to_address": "jane@acme.com", "to_name": "Jane Smith", "subject": "Quick question about Acme Corp", "personalization_fields": {"name": "Jane", "company": "Acme Corp", "role": "VP Engineering"}, "status": "opened", "sent_at": "2026-02-25T10:15:00Z", "delivered_at": "2026-02-25T10:15:02Z", "first_open_at": "2026-02-25T14:32:00Z", "open_count": 3, "clicked_at": null, "click_count": 0, "replied_at": null, "meeting_booked": false } ``` --- ## Template Variables Nova templates use `{{variable}}` syntax: 1. **Define** variables in the template's `variables` array 2. **Auto-extracted** — the frontend regex-extracts `{{word}}` from subject + body 3. **Filled per-lead** — each lead's data populates placeholders at send time Common variables: `{{name}}`, `{{company}}`, `{{role}}`, `{{custom_field}}` --- ## Block Reference | Block Type | Page | What It Shows | |-----------|------|---------------| | `nova_dashboard` | Dashboard | 6 KPIs, email volume chart, engagement funnel, activity feed, top performers, peak hours | | `nova_outbox` | Outbox | Paginated email table, 8 status filters, search, email detail sheet | | `nova_templates` | Templates | Template library, editor with {{variable}} pills, live preview, performance stats | | `nova_sequences` | Sequences | Sequence builder, multi-step flow, delays, conditions, enrollment stats | | `nova_campaigns` | Campaigns | Campaign cards with progress, 3-step wizard, pause/resume, linked emails | | `nova_analytics` | Analytics | Period selector, 8 KPIs, volume trends, engagement charts, template performance | --- ## Agent Workflows **Create and send a campaign:** 1. Create a template with {{variables}} 2. Create a sequence linking the template(s) with delays 3. Create a campaign linking the sequence + from_address + send limits 4. Load leads (CSV import or manual) with personalization fields 5. Activate the campaign — Nova sends within the daily window **Monitor engagement:** 1. Check Dashboard KPIs for overall health 2. Outbox for individual email statuses 3. Analytics for trends over time 4. Identify top-performing templates **Handle issues:** 1. High bounce rate (>5%) → clean lead list, remove invalid addresses 2. Low open rate (<20%) → test subject lines, check spam score 3. Emails in spam → verify SPF/DKIM/DMARC, warm up domain gradually 4. Send failures → check RESEND_API_KEY, verify domain status --- ## Troubleshooting **Emails not sending:** Verify `RESEND_API_KEY` in Supabase secrets + domain verified in Resend. **Going to spam:** Ensure SPF, DKIM, DMARC DNS records verified. Keep daily volume under 50 for new domains. **Open tracking off:** Resend uses a tracking pixel — some clients block images. Industry-wide limitation. **Bounces increasing:** Hard bounces = invalid address (remove). Soft bounces = temporary (retry). Above 5% = sender reputation damage.