Campaign Preflight

Campaign Preflight

Campaign Preflight is a read-only linter for outbound campaigns. It catchesconfiguration, contact-data, personalization, suppression, schedule, and senderproblems before launch.

What it does

Every outbound team has shipped a campaign with a mistake in it. Someone whounsubscribed got emailed anyway. A sequence kept following up after the prospectreplied. A merge field never merged and two hundred people got "Hi{{first_name}}."

You find out after it sends.

Campaign Preflight runs 76 deterministic checks over a campaign's configuration,leads, copy, schedule, senders, and suppression exposure, and returns areadiness decision with evidence for every finding. It never writes to yourprovider and it cannot activate anything.

What it does not do, up front rather than buried:

• It does not guarantee deliverability. It checks configuration and data,not inbox placement, and never invents a deliverability score.
• It does not give legal advice. Region, domain, and opt-out checks comparea campaign against your own configured policy — not GDPR, CAN-SPAM, or CASL.
• It does not verify mailboxes. Address checks are syntax only. No DNS, noSMTP.
• It does not replace your provider's safeguards. Keep those on.
• Results are a point-in-time snapshot. A campaign that passed at 09:00 canbe edited at 09:05.

Fuller detail in docs/limitations.md.

"We checked and it's fine" ≠ "we couldn't check"

A checker that cannot tell those apart is worse than no checker, because itturns a permissions error into a green light.

Campaign Preflight makes the distinction structural. Every provider read returnsdata plus the reason it does or does not exist, and every rule declares thedata it needs. If that data is unavailable, the engine short-circuits the ruleto UNKNOWN before it can run. Rules cannot opt out.

There are four verdicts, not two: READY, READY_WITH_WARNINGS, NOT_READY,and INCOMPLETE.

Requirements

Python 3.9 or newer. That is the whole list.

The package has no runtime dependencies — it imports nothing outside thestandard library. httpx is an optional extra needed only for the liveInstantly provider, behind a lazy import.

The 3.9 floor is deliberate, and deliberately lower than you might expect. It isthe oldest interpreter the plugin can encounter on a user's machine, and sincethere are no dependencies, nothing forces it higher. CI runs 3.9 through 3.13plus a bare-interpreter job that installs nothing at all, on Linux, macOS, andWindows.

That combination is what lets the plugin run with no install step: it useswhatever python3 is already there.

Install

As a Claude plugin (marketplace)

/plugin marketplace add katekruger/campaignpreflightplugin
/plugin install campaign-preflight

The repository is its own marketplace: .claude-plugin/marketplace.json sits atthe root alongside the plugin manifest.

As a Claude plugin (local checkout)

git clone https://github.com/katekruger/campaignpreflightplugin

/plugin marketplace add ./campaignpreflightplugin
/plugin install campaign-preflight

As a CLI

pipx install campaign-preflight

Or straight from a checkout, with nothing installed at all:

PYTHONPATH=src python3 -m campaign_preflight.cli demo

As an MCP server

claude mcp add campaign-preflight -- campaign-preflight-mcp

Six read-only tools. Nothing that could activate, edit, import, or send. Setupfor Claude Code and Claude Desktop: docs/mcp.md.

Quick start

campaign-preflight demo

No API key. No network. No configuration.

CAMPAIGN PREFLIGHT
Campaign: Enterprise Q3 Outbound
Provider: demo
Readiness: NOT READY
Score: 0/100
Confidence: MEDIUM

BLOCKERS

[campaign.stop_on_reply]
Stop-on-reply is disabled: repliers will keep receiving follow-ups.
  Remediation: Enable stop-on-reply on the campaign.

[personalization.prompt_injection]
1 contact(s) have prompt-injection text in their personalization.
  Affected: s***********[email protected]
  Remediation: Remove the affected personalization and review the enrichment source it came from.

[suppression.contact_listed]
1 contact(s) appear on the active suppression list.
  Affected: m**********[email protected]
  Remediation: Remove these contacts from the campaign before activation.

WARNINGS

[contacts.missing_first_name]
2 of 20 contacts (10.0%) are missing a first name.
  Affected: i**[email protected], r******[email protected]
  Remediation: Backfill the missing first names, or use a fallback in your copy.

UNKNOWN

[senders.aggregate_capacity]
Sender capacity is unavailable: 1 of 3 senders report no daily limit.
  Affected: r***[email protected]

------------------------------------------------------------------------------
Summary:
8 blockers, 17 failures, 21 warnings, 1 unknown, 32 passed
20 leads and 3 sender(s) checked in 0.0s
Confidence is MEDIUM: 1 check(s) could not run.
Point-in-time snapshot. Campaign state may change after this check ran.

Note the last finding. One sender reports no daily limit, so total capacitycannot be summed. Most tools would add up the senders that do report one andcall it a number. This one says it does not know — and drops confidence fromHIGH to MEDIUM because of it.

That distinction is the whole idea.

Checking your own campaign

Once the plugin is installed, describe it in plain language:

Check this campaign before I send it.

Here's my lead list — anything wrong with it? (paste or upload)

I'm sending a 3-email sequence to 200 people, 80 a day, weekdays 9-5 Eastern.Is that okay?

There are three ways in, and none needs an account:

Anything you do not know is left blank rather than guessed — a blank field comesback as "couldn't check", which is the honest answer.

From files, on the command line

campaign-preflight check \
  --campaign examples/clean_campaign/campaign.yaml \
  --leads examples/clean_campaign/leads.csv \
  --suppressions examples/clean_campaign/suppressions.csv

Three worked examples ship with the repo, one per verdict:

In CI

campaign-preflight check --campaign campaign.yaml --leads leads.csv --fail-on blocker

Exit codes carry the verdict, so this drops straight into a pipeline. Seedocs/ci.md.

What is inside

The repository root is the plugin. There is no second copy of the tree.

.claude-plugin/     plugin manifest and marketplace manifest
skills/             the three skills, one directory each
bin/                launchers the MCP server and CLI run through
src/                the Python package: rules, engine, providers, reporters
tests/              unit, integration, contract
docs/               rules catalogue, configuration, MCP, CI, limitations, architecture
examples/           three worked campaigns, one per verdict
scripts/            generators and the plugin packager

Skills

The boundaries are deliberate: each description names its own situation andpoints at its neighbour, so a near-miss lands somewhere recoverable.

What it checks

76 rules across seven categories. Full catalogue: docs/rules.md.

Ask the tool about any of them:

campaign-preflight rules list --category suppression
campaign-preflight rules explain senders.aggregate_capacity

What it deliberately does not check

There is no spam-word rule. "Free" and "act now" are not evidence of anything,and shipping that list would train you to ignore the tool. Rules that arejudgement calls — copy length, link count, generation artifacts — are markedheuristic, labelled as such in every report, and are never blockers by default.

Configuration

Campaign Preflight runs with sensible defaults and no config file. Add one whenyour thresholds differ, or to switch on the checks that depend on your owndomain and region lists.

version: 1

settings:
  target_timezone: America/New_York
  required_variables: [first_name, company_name]
  internal_domains: [ourcompany.example.com]
  customer_domains: [bigcustomer.example.com]
  allow_weekend_sending: false

rules:
  campaign.daily_volume:
    warning_above: 100
    blocker_above: 250
  senders.health_below_threshold:
    minimum_score: 80
  contacts.missing_job_title:
    enabled: false

campaign-preflight validate-config preflight.yaml
campaign-preflight check --campaign c.yaml --leads l.csv --config preflight.yaml

Validation is strict on purpose: an unknown rule id or an unknown option is ahard error, not a warning. A typo that silently disables a safety check is worsethan no config at all.

Full reference: docs/configuration.md.

Why read-only matters

Campaign Preflight has no code path that writes. Not "we chose not to" — thereis nothing to call.

• The Instantly provider routes every request through a transport that checks(method, path) against an explicit allowlist and raises before the requestleaves the process. The check sits below the client and below the provider,so a future code change that adds a PATCH fails loudly instead of quietlyediting your campaign.
• Two guards run at import time: the allowlist cannot contain PUT, PATCH,DELETE, HEAD, or OPTIONS, and POST is permitted for exactly one path(/leads/list, which is Instantly's documented shape for a filtered read).
• The MCP server refuses to start if any registered tool has a mutating verbin its name or does not declare itself read-only.
• tests/contract/test_instantly_transport.py exercises the full method × pathmatrix plus every documented mutating endpoint. A failure there is a securityincident, not a test failure.

This is what makes it safe to hand an agent a live campaign. It gets theanalysis and none of the authority.

What it will never do

• Activate, pause, resume, or schedule a campaign
• Create, update, move, merge, or delete a lead
• Add to or remove from a suppression list
• Send, reply to, or forward an email
• Modify anything in your sending platform

There is no code path to any of these, and two independent guards — thetransport allowlist and the MCP startup assertion — fail closed if one is everadded.

Exit codes

--fail-on none|warning|high|blocker raises the bar at which a verdict becomesa nonzero exit. It never changes the verdict itself. INCOMPLETE is notsilenced by a severity threshold — a check that could not run is a differentproblem from a low-severity finding.

Scoring is published, not hidden

score = 100 - sum(weight[status][severity] for every FAIL and WARN)

readiness:
  NOT_READY            any BLOCKER FAIL, or any HIGH FAIL
  INCOMPLETE           else if any critical rule is UNKNOWN
  READY_WITH_WARNINGS  else if any FAIL or WARN
  READY                otherwise

Four things follow from that, and each has a test:

1. A blocker always produces NOT_READY. The number cannot override it.
2. UNKNOWN deducts nothing. A provider outage must not look like a badcampaign — it lowers confidence instead.
3. NOT_APPLICABLE affects nothing.
4. Every deduction is itemized. --verbose prints the arithmetic so you cancheck it by hand.

Weights and the critical-rule list are configurable:docs/configuration.md.

Architecture

flowchart LR
    CLI[CLI] --> Engine
    MCP[MCP server] --> Engine
    Engine -->|gather| Provider{Provider}
    Provider --> CSV[CSV / files]
    Provider --> Instantly[Instantly v2]
    Instantly --> Guard[ReadOnlyTransport]
    Guard -->|allowlist| API[(Instantly API)]
    Provider -->|data + why| Context[Frozen context]
    Context --> Rules[76 rules]
    Rules --> Score[Scoring]
    Score --> Out[Terminal / JSON / Markdown]
    style Guard fill:#4a1f1f,stroke:#c04040,color:#fff

The context is a frozen Pydantic model, so "a rule never mutates its input" isenforced by the type system rather than by review. Provider-specific behaviourlives entirely behind the provider interface.

Full design and threat model: docs/architecture.md.

Privacy

• Redacted by default. Mailbox local parts are masked(m**********[email protected]); domains are kept, because a domainis what makes a suppression finding actionable.
• Secrets are scrubbed unconditionally. --no-redact disables PII masking,never credential masking. A provider that echoes your API key back in an errorbody cannot get it into a report — there is a test for exactly that.
• Nothing leaves your machine by default. The optional LLM claim evaluatoris off unless you configure it, and validate-config warns you when a configturns it on.
• Report files are written 0600, to a temporary file and then renamed.
• Samples are bounded. A 100,000-lead campaign cannot emit 100,000 lines.

Performance

Rows are streamed, not slurped. Pagination, retries, sender concurrency, andoutput size are all bounded.

Development

git clone https://github.com/katekruger/campaignpreflightplugin
cd campaignpreflightplugin
uv sync --all-extras
uv run pytest

uv run ruff format .                                  # format
uv run ruff check .                                   # lint
uv run mypy                                           # typecheck, strict
claude plugin validate . --strict                     # manifests
uv run python scripts/generate_rules_doc.py --check   # docs/rules.md is current
./scripts/bump-version.sh --check                     # version fields agree
uv run python scripts/build_plugin.py                 # dist/campaign-preflight.plugin

The package itself has no runtime dependencies; the dev group exists for thetest suite, the linters, and two libraries used only as test oracles — httpxfor the optional Instantly provider and PyYAML to differentially test thebundled YAML parser against.

Conventions that look like mistakes until you know why are written down inCLAUDE.md.

Roadmap

• Additional providers behind the same read-only interface (Smartlead,HubSpot Sequences, Apollo)
• Domain reputation and DNS record checks (SPF, DKIM, DMARC alignment)
• A GitHub Action wrapping the CLI with PR annotations
• Baseline comparison: diff two reports and show what changed since the last run
• Per-segment thresholds, so one config can cover several motions

Contributing

Rules are small, pure, and independently testable — a new one is usually aclass, a docstring, and a handful of tests. SeeCONTRIBUTING.md andCODE_OF_CONDUCT.md.

Security

Report vulnerabilities privately: SECURITY.md. A rule thatreturned PASS when the data was missing counts as a security issue.

License

MIT. See LICENSE.