agentleFS
MattSezginMattSezgin/unofficial-smartlead-cli/.claude/skills/upload-leads/SKILL.md

upload-leads

Skill8 starsChanged 6 months agoMITView on GitHub

Upload leads from a CSV file to a Smartlead campaign with automatic deduplication, 100-per-batch pagination, and lead-validation. Reports added vs skipped vs failed counts. Use when the user wants to upload, import, add, or push leads to a campaign — from a CSV, JSON, or any structured lead list.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Look at the file first. Confirm columns:

    line 20
  2. Distinctive:

    If the user has 1000+ leads and bounces matter, recommend pre-validating with an external service before upload.

    line 47
  3. Very specific:

    Should match expected count.

    line 98

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Before running: verify exact flag names with smartlead <command> --help. Flag shapes shown below are illustrative — confirm against the actual CLI.

/upload-leads

You're loading a lead list into a Smartlead campaign.

What you need from the user

  • Campaign ID to upload to
  • Lead source — CSV path, JSON file, or pasted list
  • Dedup scope — just this campaign, or check against all campaigns?

Step 1 — Validate the source

Look at the file first. Confirm columns:

  • email (required)
  • first_name, last_name (recommended)
  • company_name (recommended)
  • linkedin_url, phone_number, website (optional)
  • Anything else → goes into custom_fields for personalization
head -5 <csv-path>
wc -l <csv-path>

Report row count, column names, and a sample row. Confirm with user before uploading.

Step 2 — Pre-validation

Filter obviously bad emails

# Emails missing @, or with invalid TLD
grep -E '^[^@]+@[^@]+\.[a-z]{2,}$' leads.csv > leads-cleaned.csv

Flag count of dropped rows.

Optional: ZeroBounce / NeverBounce validation

If the user has 1000+ leads and bounces matter, recommend pre-validating with an external service before upload. Smartlead doesn't validate emails at upload time.

Step 3 — Dedupe

Against this campaign

smartlead leads list <campaign_id> --output json | jq -r '.[].email' > existing.txt

Then filter the upload CSV:

awk -F, 'NR==FNR{a[$1]; next} !($1 in a)' existing.txt leads.csv > new-leads.csv

Against all live campaigns (broader dedup)

Important for B2B — you don't want the same prospect getting hit by Campaign A AND Campaign B.

# Pull emails from all active campaigns
smartlead campaigns list --output json | jq -r '.[] | select(.status == "ACTIVE") | .id' | \
  while read cid; do
    smartlead leads list $cid --output json | jq -r '.[].email'
  done | sort -u > all-active.txt

# Filter
awk -F, 'NR==FNR{a[$1]; next} !($1 in a)' all-active.txt leads.csv > new-leads.csv

Report: started with X leads, after dedup Y remain (Z dropped).

Step 4 — Batch upload (Smartlead caps at 100 per request)

The CLI handles pagination, but if you're hitting the API directly:

smartlead leads add <campaign_id> --csv new-leads.csv

The command splits into 100-row batches automatically and reports per-batch results.

For very large files (10K+), recommend uploading in chunks of 5K with a sleep between, to stay well under rate limits (see docs/learnings/rate-limits.md).

Step 5 — Verify upload

smartlead leads list <campaign_id> --output json | jq 'length'

Should match expected count. If short, look at the upload command's error log — Smartlead silently rejects rows with malformed custom_fields.

Step 6 — Report

Summarize for the user:

✓ Uploaded X new leads to campaign <id>
✓ Skipped Y duplicates (already in this or other campaigns)
✓ Dropped Z invalid rows (bad email format / missing required fields)
Campaign now has N total leads.

Important gotcha — leads are shared across campaigns

Smartlead's data model is: email = unique lead at the account level, NOT per-campaign. If you upload the same email to Campaign A then to Campaign B:

  • Both campaigns reference the SAME lead record
  • custom_fields set on Campaign A propagate to Campaign B's view of that lead
  • You CAN'T have per-campaign custom_fields for the same email

Practical implication: if you're A/B testing personalization fields, use DIFFERENT emails (or different campaigns with different lead pools), not the same lead in two campaigns.

(More: docs/learnings/campaign-cloning-runbook.md)

Reference

  • docs/learnings/campaign-cloning-runbook.md — lead-sharing behavior
  • docs/learnings/rate-limits.md — pagination and throttling

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.