clay-alt-route-to-instantly

---
name: clay-alt-route-to-instantly
description: Push copy-ready leads from the Clay Alt Platform Supabase to Instantly as a single-send-or-sequence upload. Gated by campaign.config.route_to_instantly — in v1 this skill is a no-op when the flag is false, so the pipeline can be tested end-to-end without a paid Instantly account. Use as the final stage of the outbound routine, after copy has been generated.
allowed-tools: Bash
---

# clay-alt-route-to-instantly

Send-layer integration. Takes leads that reached `status='copy_ready'` and uploads them to an Instantly campaign. Respects a per-campaign gate so v1 tests don't accidentally send.

## When to use

- Routine reaches its final stage after copy generation
- Campaign config has `route_to_instantly: true` AND a valid `instantly_campaign_id`
- At least one lead is in `status='copy_ready'` for the campaign

## When NOT to use

- Campaign config has `route_to_instantly: false` (v1 reference campaign, dry runs) — skill must **exit 0 with a noop message**
- No Instantly API key in environment (`INSTANTLY_API_KEY` unset) — exit 0 with warning, let the caller decide
- Lead already has `instantly_id` populated (already uploaded — skip to avoid duplicate)

## Input contract

```json
{
  "campaign_id": "uuid",
  "campaign_config": { "route_to_instantly": bool, "instantly_campaign_id": "..." }
}
```

## Output contract

Print one JSON object to stdout summarizing the run:

```json
{
  "uploaded": 7,
  "skipped_existing": 2,
  "errors": 1,
  "noop_reason": null
}
```

If gated off: `{"uploaded":0,"skipped_existing":0,"errors":0,"noop_reason":"route_to_instantly=false"}`.

## How

### Step 1: Gate check

Inspect `campaign_config.route_to_instantly`. If false, emit the noop JSON and exit 0. No Supabase queries, no Instantly calls.

### Step 2: Env check

Require `INSTANTLY_API_KEY` and `campaign_config.instantly_campaign_id`. If either missing, emit noop with an explanatory `noop_reason` and exit 0 (non-fatal — caller can handle).

### Step 3: Pull leads

Source `platform/lib/supabase.sh` and call:

```bash
sb_select leads "campaign_id=eq.$CID&status=eq.copy_ready&instantly_id=is.null"
```

### Step 4: Upload via Instantly

Source `platform/lib/instantly.sh` and call `instantly_add_leads` with the campaign's `instantly_campaign_id` and the lead batch. Instantly accepts up to 500 leads per call.

### Step 5: Update Supabase

For each successfully uploaded lead, patch the row:
- `status` → `'queued'`
- `instantly_id` → the ID returned by Instantly

### Step 6: Emit summary

Count uploaded / skipped / errors. Emit the JSON summary.

## v1 default behavior

The reference campaign sets `route_to_instantly: false`. This skill should return immediately with the noop JSON. End-to-end routine tests thus pass without any Instantly account or API key.

## Safety

- Never send to leads with `email_verified=false` unless `campaign_config.allow_unverified_send` is explicitly true. Deliverability collapses on bad sends.
- Batch size cap 500 per upload call (Instantly limit).
- On Instantly API error, mark the row's `provider_raw.instantly_error` with the response body and keep `status='copy_ready'` — next routine run will retry.