Smartlead

Manage Smartlead campaigns, leads, and webhooks from the command line via the smartlead CLI.

Security Scan

The skill's requirements, instructions, and helper script are consistent with a Smartlead CLI integration and OpenClaw webhook setup; nothing in the bundle appears disproportionate or out of scope.

Purpose & Capability

Name/description (Smartlead CLI management) align with the actual requirements: the smartlead binary and the SMARTLEAD_API_KEY. References to OpenClaw webhook integration in SKILL.md and setup.sh are coherent with the stated purpose.

Instruction Scope

SKILL.md stays within the Smartlead / OpenClaw integration scope (running smartlead CLI commands, fetching message-history, summarizing replies, configuring webhooks). It does reference reading the Smartlead CLI config (~/.config/smartlead-cli/config.toml) and optional environment variables (SMARTLEAD_BASE_URL, SMARTLEAD_PRETTY); those are reasonable for a CLI integration but worth noting because they expose where credentials/config can be read from.

Install Mechanism

No install spec in the registry (instruction-only). setup.sh only prints configuration and suggests optional local/plugin installation or using pip3/uv to install the smartlead-cli; it does not download or execute remote code by URL. This is low-risk for install mechanism.

Credentials

Declared required credential is a single SMARTLEAD_API_KEY (primaryEnv) which is appropriate. The helper script and docs also reference optional env vars (OPENCLAW_HOOKS_TOKEN, OPENCLAW_GATEWAY_BASE_URL, SMARTLEAD_WEBHOOK_PUBLIC_URL, SMARTLEAD_BASE_URL, SMARTLEAD_PRETTY) that are reasonable for OpenClaw integration but are not listed as required — expect these to be used only for optional setup steps and webhook configuration.

Persistence & Privilege

Skill is not forced-always (always:false). It does not request persistent/privileged system changes; setup.sh prints config snippets and suggests installing a plugin in linked mode but does not auto-modify system-wide settings or other skills' configs.

Assessment

This skill appears to do what it says: run the smartlead CLI and help wire Smartlead EMAIL_REPLY webhooks into OpenClaw. Before installing or running setup.sh: 1) verify you trust the smartlead CLI binary/package you will use (it runs commands and will access lead data); 2) keep in mind the skill will read the Smartlead CLI config (~/.config/smartlead-cli/config.toml) and use SMARTLEAD_API_KEY — treat that key like any API secret; 3) setup.sh references a local plugin directory (/home/worker/code/openclaw-smartlead) and the OPENCLAW_HOOKS_TOKEN — only run it if the plugin code at that path is trusted and you want to register an OpenClaw mapping; 4) if you plan to install smartlead-cli via pip/uv, inspect the package source before installing. If you want higher assurance, ask the publisher for the plugin repository/homepage or audit the OpenClaw plugin code referenced by the setup script before enabling it.

Smartlead — CLI Usage Guide

Smartlead is the email outreach platform used by this workspace. Use smartlead CLI commands to manage campaigns, leads, webhooks, and message history.

Configuration

Credentials are resolved in order: ~/.config/smartlead-cli/config.toml → env vars → CLI flags.

Required:

• SMARTLEAD_API_KEY — Smartlead API key

Optional:

• SMARTLEAD_BASE_URL — base URL (default https://server.smartlead.ai/api/v1)
• SMARTLEAD_PRETTY — set to 1 for rich table output

All commands output JSON by default. Add --pretty for human-readable tables (avoid in scripts).

Command Discovery (Use This Instead of Memorizing Commands)

Do not guess command names or options. Use --help and follow the CLI surface:

smartlead --help
smartlead campaigns --help
smartlead campaigns leads --help
smartlead webhooks --help
smartlead <group> <command> --help

Prefer curated commands (campaigns, leads, webhooks) over raw. Use raw only when the CLI does not expose the endpoint you need yet.

For openclaw-smartlead plugin setup, keep plugin config minimal unless there is a clear reason not to:

• usually set only webhookSecret (plugin ingress auth)
• plugin forwards normalized Smartlead payloads to OpenClaw /hooks/smartlead by default
• prompt text / delivery channel / branching logic should live in OpenClaw hooks.mappings (or a hook transform), not plugin config
• openclawHookUrl / openclawHookToken are typically auto-derived from OpenClaw hooks config

Common Workflows

Find campaign IDs

smartlead campaigns list

Get full email thread for a lead (most important for reply alerts)

# When you have campaign_id and lead_id directly:
smartlead campaigns leads message-history <campaign_id> <lead_id>

# When you only have an email address:
smartlead leads get-by-email --email [e-mail]   # → get id field
smartlead campaigns leads message-history <campaign_id> <resolved_lead_id>

Inspect / patch a lead safely (preferred over full update)

smartlead campaigns leads update is a full update endpoint and Smartlead requires email in the body. For partial edits, prefer patch because it auto-fetches the current lead, merges your changes, and sends a valid full payload.

smartlead campaigns leads get <campaign_id> <lead_id>
smartlead campaigns leads patch <campaign_id> <lead_id> --first-name "Updated"

Reply Alert Workflow (EMAIL_REPLY webhook event)

When an EMAIL_REPLY webhook fires through openclaw-smartlead, your OpenClaw hook mapping/transform should construct the prompt. The forwarded payload includes flat fields like campaign_id, lead_id, lead_email, reply_category, preview_text, message_id, sequence_number, plus payload (sanitized raw Smartlead payload).

When responding to the hook prompt, always follow this sequence:

1. Extract campaign_id and lead_id from the prompt context.
   • lead_id comes from sl_email_lead_id (not sl_email_lead_map_id).
2. If lead_id is present: smartlead campaigns leads message-history <campaign_id> <lead_id>
3. If lead_id is missing but lead_email is present: smartlead leads get-by-email --email <lead_email> → then message-history.
4. Summarize the conversation (bullets or short paragraph).
5. Send a channel message starting with exactly "New lead answer", including:
   • Lead email, campaign ID
   • One-line reply preview (from preview_text)
   • The conversation summary

Set up a campaign webhook pointing at openclaw

# List current webhooks first
smartlead webhooks list <campaign_id>

# Create/update (id: null = create new)
smartlead webhooks upsert <campaign_id> --body-file webhook.json

Example webhook.json:

{
  "id": null,
  "name": "OpenClaw Reply Alerts",
  "webhook_url": "https://<your-openclaw-host>/smartlead/webhook",
  "event_types": ["EMAIL_REPLY"],
  "categories": ["Interested"]
}

Use smartlead webhooks upsert --help for the current allowed event_types. categories are Smartlead workspace lead-category labels (for example Interested), not webhook event types.

For OpenClaw side setup, prefer:

• plugin route /smartlead/webhook for Smartlead ingress/auth/dedupe
• OpenClaw hooks.mappings on /hooks/smartlead for prompt templates and branching
• optional hook transform for deterministic routing like positive/negative/OOO handling

Webhook Payload Fields (EMAIL_REPLY)

Key fields available when an EMAIL_REPLY event arrives:

Field	Description
campaign_id	Smartlead campaign ID
sl_email_lead_id	Lead ID (use this for message-history)
sl_email_lead_map_id	Lead-map ID (different from lead_id — do not confuse)
sl_lead_email	Original target lead email
leadCorrespondence.targetLeadEmail	More reliable target email field
leadCorrespondence.replyReceivedFrom	Actual email that replied (may differ from target)
subject	Email subject
preview_text	Reply preview snippet
event_timestamp	ISO timestamp of the reply
secret_key	Webhook validation secret (set in Smartlead)

Important Edge Cases / Pitfalls

Mistake	Fix
Guessing CLI options	Use smartlead ... --help for the exact command shape
Using smartlead campaigns list --limit ...	/campaigns does not support limit; use --offset, --client-id, --include-tags
Using sl_email_lead_map_id as lead_id	Use sl_email_lead_id for message-history
Treating replyReceivedFrom as the target	targetLeadEmail is who was originally emailed
Using campaigns leads update without email	Smartlead rejects it; prefer campaigns leads patch, or include email in the full update body
Email lookups failing due to case mismatch	Normalize emails to lowercase before get-by-email / updates
Sending webhook categories: []	categories must be a non-empty list of Smartlead lead category labels
Assuming webhook categories is a global enum	Categories are workspace-specific labels (e.g. Interested); inspect Smartlead UI / Test Webhook
Running --pretty in automated scripts	Drop --pretty, parse JSON output
Starting alert without "New lead answer"	First line must be exactly New lead answer
Forgetting auth	Ensure SMARTLEAD_API_KEY is set in env or config

Deletion Behavior

Delete commands prompt for confirmation in interactive shells. In scripts/automation, pass --yes to skip prompts.

Examples:

smartlead campaigns delete <campaign_id>
smartlead campaigns leads delete <campaign_id> <lead_id>
smartlead webhooks delete <campaign_id> --webhook-id <id>