# Upload Leads

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-mattsezgin-unofficial-smartlead-cli-upload-leads`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [MattSezgin](https://agentstack.voostack.com/s/mattsezgin)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [MattSezgin](https://github.com/MattSezgin)
- **Source:** https://github.com/MattSezgin/unofficial-smartlead-cli/tree/main/.claude/skills/upload-leads
- **Website:** https://github.com/MattSezgin/unofficial-smartlead-cli

## Install

```sh
agentstack add skill-mattsezgin-unofficial-smartlead-cli-upload-leads
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **Before running:** verify exact flag names with `smartlead  --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

```bash
head -5 
wc -l 
```

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

## Step 2 — Pre-validation

### Filter obviously bad emails

```bash
# 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

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

Then filter the upload CSV:

```bash
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.

```bash
# 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:

```bash
smartlead leads add  --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

```bash
smartlead leads list  --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 
✓ 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MattSezgin](https://github.com/MattSezgin)
- **Source:** [MattSezgin/unofficial-smartlead-cli](https://github.com/MattSezgin/unofficial-smartlead-cli)
- **License:** MIT
- **Homepage:** https://github.com/MattSezgin/unofficial-smartlead-cli

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mattsezgin-unofficial-smartlead-cli-upload-leads
- Seller: https://agentstack.voostack.com/s/mattsezgin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.