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.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- audit-mailbox-configSkill
- check-deliverabilitySkill
- clone-campaignSkill
- compare-campaignsSkill
- create-campaignSkill
- launch-campaignSkill
- smartlead-onboardingSkill
- spam-testSkill
- warmup-mailboxesSkill
- weekly-reportSkill
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
- Distinctive: line 20
Look at the file first. Confirm columns:
- Distinctive: line 47
If the user has 1000+ leads and bounces matter, recommend pre-validating with an external service before upload.
- Very specific: line 98
Should match expected count.
≈ “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.
Files
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_fieldsfor 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.csvFlag 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.txtThen filter the upload CSV:
awk -F, 'NR==FNR{a[$1]; next} !($1 in a)' existing.txt leads.csv > new-leads.csvAgainst 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.csvReport: 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.csvThe 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_fieldsset 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 behaviordocs/learnings/rate-limits.md— pagination and throttling
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
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.

