fivos-campaign-launcher

Fivos Campaign Launcher

Final step. Takes the copy-ready CSV and the campaign plan, creates the campaign in the chosen sequencer, pushes leads, runs the pre-flight checklist, activates.

Hard rules

• One sequencer per tier. Do not split a single tier's contacts across Instantly + Smartlead. Match the strategist's routing rules.
• Pre-flight checklist must pass before activation. No exceptions.
• Inbox health is checked at push time, not launch time. If any inbox is below warmup threshold, abort.
• Never activate a campaign without the engineer's explicit final confirmation. Campaign created + leads pushed = fine. Activate = requires confirmation.
• Tracking pixels and click-tracked links are off by default for cold outbound. Gmail / Outlook dings deliverability on these. Only enable when explicitly requested.

Inputs

• Copy CSV from fivos-copywriter.
• Campaign plan from fivos-campaign-strategist (sequence shape, routing rules, volume math).
• Sequencer choice per tier (Instantly / Smartlead / Lemlist / HeyReach).
• Inbox assignment - which inbox cluster sends for which geo / tier.
• Campaign name - standard format: <client>_<tier>_<segment>_<YYYYMM>.

Outputs

1. Created campaign ID(s) per sequencer.
2. Lead push confirmation (count pushed vs expected).
3. Pre-flight checklist result.
4. Activation status (scheduled / live / paused).
5. Rollback instructions (in case of post-launch issue).

Pre-flight checklist (runs before any activation)

All must pass:

1. Domain health - every sending domain has SPF + DKIM + DMARC set. DMARC at least p=quarantine.
2. Inbox warmup - every inbox has been warming >=14 days and is at >=30 sends/day warmup volume.
3. List hygiene - 100% of emails are deliverable or catch_all_safe (from fivos-contact-enrichment verification).
4. Copy QA - no AI-tell blocklist hits survived to this stage.
5. Unsubscribe + physical address - present on every email (CAN-SPAM / GDPR).
6. Daily send cap - set to <=40 per inbox for cold starts (ramp up only after 2 weeks of stable positive-reply rate).
7. Send window - recipient timezone-aware, working hours only.
8. Duplicate scan - no lead already in another active campaign for this client.

Print the checklist with pass/fail per item before activation.

Workflow

Step 1 - Campaign creation per sequencer

Instantly (MCP already wired - mcp__instantly__*):

# Create campaign
mcp__instantly__create_campaign({
  name: "acme_bullseye_us-saas_202604",
  sequences: <built from sequence_shape + copy_columns>,
  sending_accounts: <inbox cluster IDs>,
  schedule: <send_window_per_geo>,
  campaign_settings: {
    stop_on_reply: true,
    stop_on_auto_reply: true,
    link_tracking: false,
    open_tracking: false,
    text_only: true
  }
})

HeyReach (REST API, LinkedIn plays):

HeyReach is the LinkedIn sequencer. API is REST-based. User configures HEYREACH_API_KEY in env; the skill calls via Bash + curl.

# Create a campaign
curl -X POST https://api.heyreach.io/api/public/campaign/CreateCampaign \
  -H "X-API-KEY: $HEYREACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme_bullseye_li_202604",
    "linkedInAccountIds": [<seat IDs>],
    "steps": [
      {"type": "CONNECT", "delayDays": 0, "message": "<connection note>"},
      {"type": "MESSAGE", "delayDays": 2, "message": "<follow-up 1>"},
      {"type": "MESSAGE", "delayDays": 4, "message": "<follow-up 2>"}
    ]
  }'

# Add leads
curl -X POST https://api.heyreach.io/api/public/lead/AddLeadsToCampaign \
  -H "X-API-KEY: $HEYREACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": <id>,
    "leads": [
      {"linkedInUrl": "<url>", "firstName": "<f>", "lastName": "<l>", "customFields": {...}},
      ...
    ]
  }'

# Start (activate)
curl -X POST https://api.heyreach.io/api/public/campaign/StartCampaign \
  -H "X-API-KEY: $HEYREACH_API_KEY" \
  -d '{"campaignId": <id>}'

# Pause (rollback)
curl -X POST https://api.heyreach.io/api/public/campaign/PauseCampaign \
  -H "X-API-KEY: $HEYREACH_API_KEY" \
  -d '{"campaignId": <id>}'

HeyReach status: API key pending configuration. Once HEYREACH_API_KEY is in env, these calls work directly.

Smartlead / Lemlist: follow the same shape through each provider's API. Playbooks in gtm-meta-skill/provider-playbooks/. Their MCPs are not wired in this environment - use REST until they are.

Step 2 - Push leads in controlled batches

Push in batches of 50-100 per call. After each batch:

• Re-fetch campaign stats to confirm lead count.
• Check for rejected leads (sequencer-side dedup, bad format).
• Log every reject to the run ledger.

Instantly example:

mcp__instantly__add_leads_to_campaign_or_list_bulk({
  campaign_id: <id>,
  leads: <batch of 50>
})

Step 3 - Pre-flight run

Run all 8 checklist items. Any fail = stop and surface to the engineer. Do not auto-fix.

Step 4 - Dry-run preview

Render the first 3 contacts' full sequence (all touches, subject + body + LI messages) as the sequencer will render them. Show the engineer:

Preview - <campaign_name>

Contact: John Smith (Acme Corp)
Tier: A

[T+0] Email 1
  From: [email protected]
  Subject: saw the Series B
  Body:
    Saw the Series B closed last week...
    ...

[T+3] Email 2
  ...

[T+2] LI: connection request
  ...

Step 5 - Final activation

Ask explicit confirmation:

Ready to activate <campaign_name>?

Leads pushed: N
Sequencer: Instantly
Inboxes: <list>
Daily volume: X sends/day
First send: <date/time>

Type "activate" to go live.

Only on explicit "activate" does the skill flip the campaign to live.

mcp__instantly__activate_campaign({ campaign_id: <id> })

Step 6 - Post-launch snapshot

Record to the internal DB:

campaign_launch_log:
  client: <client>
  campaign: <name>
  sequencer_id: <id>
  launched_at: <timestamp>
  leads_pushed: N
  expected_daily_sends: X
  first_expected_send: <date>
  rollback_command: <how to pause if needed>

Rollback

If anything looks wrong in the first 24 hours, pause immediately. Pausing is cheap.

Instantly:

mcp__instantly__pause_campaign({ campaign_id: <id> })

HeyReach:

curl -X POST https://api.heyreach.io/api/public/campaign/PauseCampaign \
  -H "X-API-KEY: $HEYREACH_API_KEY" \
  -d '{"campaignId": <id>}'

Smartlead / Lemlist: see their playbooks for equivalent pause commands.

Handoff

Invoke fivos-campaign-analysis to set up the reporting cadence (weekly pulls).

References

• ~/.agents/skills/gtm-meta-skill/provider-playbooks/instantly.md
• ~/.agents/skills/gtm-meta-skill/provider-playbooks/smartlead.md
• ~/.agents/skills/gtm-meta-skill/provider-playbooks/lemlist.md
• ~/.agents/skills/gtm-meta-skill/provider-playbooks/heyreach.md
• Instantly MCP tools: mcp__instantly__* (already wired in this environment).
• HeyReach REST API: https://api.heyreach.io/api/public/* (config pending - HEYREACH_API_KEY env var).