pp-smartlead

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SmartLead — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

smartlead-pp-cli

binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer:

bash

npx -y @mvanhorn/printing-press-library install smartlead --cli-only

Verify:
```
smartlead-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

bash

go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/smartlead/cmd/smartlead-pp-cli@latest

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

此技能驱动

smartlead-pp-cli

二进制文件。在调用此技能的任何命令之前，您必须验证CLI已安装。如果未安装，请先进行安装：

通过Printing Press安装程序安装：

bash

npx -y @mvanhorn/printing-press-library install smartlead --cli-only

验证：
```
smartlead-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等），请改用直接Go安装（需要Go 1.26.3或更高版本）：

bash

go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/smartlead/cmd/smartlead-pp-cli@latest

如果安装后

--version

提示“command not found”，说明安装步骤未将二进制文件添加到

$PATH

中。在验证成功前，请不要继续使用技能命令。

When to Use This CLI

何时使用此CLI

Use this CLI when an agent or operator needs to audit cold-email outreach in SmartLead: checking which campaigns are healthy, building follow-up lists of silent leads, deduplicating leads across campaigns before launch, or ranking sender accounts by deliverability. It is the right tool when the question spans multiple campaigns or needs week-over-week history, because those answers come from the local mirror rather than a single API call.

当Agent或操作人员需要审计SmartLead中的冷邮件推广活动时，可使用此CLI：检查哪些活动运行正常、构建沉默线索的跟进列表、在活动启动前跨活动去重线索，或者根据送达率对发件人账户进行排名。当问题涉及多个活动或需要周环比历史数据时，这是合适的工具，因为这些答案来自本地镜像而非单次API调用。

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.

这些功能是其他同API工具所不具备的。

Local state that compounds

可累积的本地状态

health
— One-shot scorecard for every campaign — bounce rate, reply rate, silent-lead count, sender count, and a stale flag — without clicking through the dashboard.
Reach for this first when an agent needs to know which campaigns are healthy before drilling into any one of them.
bash
```
smartlead-pp-cli health --json
```
silent
— Finds leads that were emailed but have not replied within N days — the exact set to follow up with or retire.
Use this to build a follow-up list instead of paging the whole lead set and diffing timestamps by hand.
bash
```
smartlead-pp-cli silent --campaign 12345 --days 7 --json
```
dupes
— Scans the whole lead mirror for emails or domains that appear in two or more campaigns; --domain prints the full pitch ledger for one site.
Run this before adding leads to a campaign to avoid double-contacting a prospect already in flight.
bash
```
smartlead-pp-cli dupes --domain example.com --json
```
drift
— Computes week-over-week reply, open, and bounce deltas for a campaign by querying analytics one seven-day window at a time.
Use this to catch a campaign decaying over time rather than judging it from a single point-in-time stat.
bash
```
smartlead-pp-cli drift --campaign 12345 --weeks 4 --json
```

health
— 一次性生成所有活动的计分卡——包含bounce rate、reply rate、沉默线索数量、发件人数量以及过期标记——无需在仪表板中逐个点击查看。
当Agent需要在深入单个活动前了解哪些活动运行正常时，首先使用此命令。
bash
```
smartlead-pp-cli health --json
```
silent
— 查找已发送邮件但N天内未回复的线索——这正是需要跟进或标记为无效的线索集合。
使用此命令构建跟进列表，无需手动翻页整个线索集并比较时间戳。
bash
```
smartlead-pp-cli silent --campaign 12345 --days 7 --json
```
dupes
— 扫描整个线索镜像，查找出现在两个或多个活动中的邮箱或域名；使用
```
--domain
```
可打印某个站点的完整推广记录。
在向活动添加线索前运行此命令，避免重复联系已在跟进中的潜在客户。
bash
```
smartlead-pp-cli dupes --domain example.com --json
```
drift
— 通过逐个查询七天窗口期的分析数据，计算活动的周环比回复率、打开率和退信率变化。
使用此命令发现活动随时间的衰退情况，而非仅根据单一时间点的数据进行判断。
bash
```
smartlead-pp-cli drift --campaign 12345 --weeks 4 --json
```

Deliverability intelligence

送达率智能分析

sender-health
— Ranks every email sender account by a composite of inbox-warmup landing rate, SMTP/IMAP connection health, and sending utilization.
Reach for this to find which sender accounts are dragging deliverability before they tank a campaign.
bash
```
smartlead-pp-cli sender-health --json
```
warmup-gate
— Checks each sender account against warmup thresholds (--min-days, --min-inbox-rate); with --strict it exits non-zero when any account fails — a scriptable launch gate.
Call this in a launch script to block attaching a sender account that is not warmed up yet.
bash
```
smartlead-pp-cli warmup-gate --account 6789 --json
```

sender-health
— 根据收件箱预热着陆率、SMTP/IMAP连接健康状况和发送使用率的综合指标，对所有邮件发件人账户进行排名。
当需要找出哪些发件人账户正在拉低送达率，避免其影响活动效果时，使用此命令。
bash
```
smartlead-pp-cli sender-health --json
```
warmup-gate
— 检查每个发件人账户是否符合预热阈值（
```
--min-days
```
、
```
--min-inbox-rate
```
）；使用
```
--strict
```
时，若任何账户未达标则返回非零退出码——这是一个可脚本化的启动校验机制。
在启动脚本中调用此命令，阻止添加尚未完成预热的发件人账户。
bash
```
smartlead-pp-cli warmup-gate --account 6789 --json
```

Command Reference

命令参考

campaigns — Manage campaigns

```
smartlead-pp-cli campaigns create
```
— Create a new campaign
```
smartlead-pp-cli campaigns delete
```
— Delete a campaign
```
smartlead-pp-cli campaigns get
```
— Get a campaign by ID
```
smartlead-pp-cli campaigns list
```
— Retrieves every email campaign for the authenticated SmartLead account.

client — Manage client

```
smartlead-pp-cli client create
```
— Create a whitelabel client
```
smartlead-pp-cli client list
```
— List all whitelabel clients

email-accounts — Manage email accounts

```
smartlead-pp-cli email-accounts create
```
— Add a new email sender account
```
smartlead-pp-cli email-accounts list
```
— List all email sender accounts
```
smartlead-pp-cli email-accounts reconnect-failed
```
— Trigger a reconnect of all disconnected email accounts
```
smartlead-pp-cli email-accounts update
```
— Update an email sender account

leads — Manage leads

```
smartlead-pp-cli leads add-domain-block-list
```
— Add domains to the account-wide block list
```
smartlead-pp-cli leads get-by-email
```
— Look up a lead by email address
```
smartlead-pp-cli leads list-categories
```
— List all lead categories for the account
```
smartlead-pp-cli leads update
```
— Update a lead's fields

campaigns — 管理活动

```
smartlead-pp-cli campaigns create
```
— 创建新活动
```
smartlead-pp-cli campaigns delete
```
— 删除活动
```
smartlead-pp-cli campaigns get
```
— 通过ID获取活动信息
```
smartlead-pp-cli campaigns list
```
— 获取已认证SmartLead账户下的所有邮件活动。

client — 管理客户端

```
smartlead-pp-cli client create
```
— 创建白标客户端
```
smartlead-pp-cli client list
```
— 列出所有白标客户端

email-accounts — 管理邮件账户

```
smartlead-pp-cli email-accounts create
```
— 添加新的邮件发件人账户
```
smartlead-pp-cli email-accounts list
```
— 列出所有邮件发件人账户
```
smartlead-pp-cli email-accounts reconnect-failed
```
— 触发所有断开连接的邮件账户重新连接
```
smartlead-pp-cli email-accounts update
```
— 更新邮件发件人账户信息

leads — 管理线索

smartlead-pp-cli leads add-domain-block-list

— 向账户级黑名单添加域名

```
smartlead-pp-cli leads get-by-email
```
— 通过邮箱地址查找线索
```
smartlead-pp-cli leads list-categories
```
— 列出账户下的所有线索分类
```
smartlead-pp-cli leads update
```
— 更新线索字段

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:

bash

smartlead-pp-cli which "<capability in your own words>"

which

resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code

means at least one match; exit code

means no confident match — fall back to

--help

or use a narrower query.

当您知道要执行的操作但不知道对应的命令时，可直接询问CLI：

bash

smartlead-pp-cli which "<用您自己的语言描述功能>"

which

命令会将自然语言的功能查询解析为与此CLI精选功能索引最匹配的命令。退出码

表示至少有一个匹配项；退出码

表示没有确定的匹配项——此时请改用

--help

或缩小查询范围。

Recipes

使用示例

Morning campaign triage

晨间活动分类处理

bash

smartlead-pp-cli sync && smartlead-pp-cli health --json

Refresh the mirror, then get the all-campaigns health scorecard in one structured payload.

bash

smartlead-pp-cli sync && smartlead-pp-cli health --json

刷新本地镜像，然后一次性获取所有活动的健康计分卡结构化数据。

Pre-launch dedupe check

启动前去重检查

bash

smartlead-pp-cli dupes --domain prospect-site.com --json

See every campaign, category, and last-contact date for a domain before pitching it again.

bash

smartlead-pp-cli dupes --domain prospect-site.com --json

在再次推广某个域名前，查看该域名对应的所有活动、分类和最后联系日期。

Build a follow-up list

构建跟进列表

bash

smartlead-pp-cli silent --campaign 12345 --days 10 --json

Pull leads emailed but silent for 10+ days to feed into a follow-up sequence.

bash

smartlead-pp-cli silent --campaign 12345 --days 10 --json

提取已发送邮件但10天以上无回复的线索，用于跟进序列。

Trim a verbose campaign payload

精简冗长的活动数据

bash

smartlead-pp-cli campaigns list --agent --select id,name,status

SmartLead campaign objects are large; --agent with --select narrows the response to just the fields an agent needs.

bash

smartlead-pp-cli campaigns list --agent --select id,name,status

SmartLead的活动对象数据量较大；使用

--agent

搭配

--select

可将响应内容缩小到Agent所需的字段。

Gate a launch on sender warmup

基于发件人预热状态校验活动启动

bash

smartlead-pp-cli warmup-gate --account 6789 --json

Returns a typed exit code so a launch script can block on a sender that is not warmed up.

bash

smartlead-pp-cli warmup-gate --account 6789 --json

返回类型化退出码，以便启动脚本可阻止使用未完成预热的发件人账户。

Auth Setup

认证设置

SmartLead authenticates with an API key passed as the api_key query parameter. Set SMARTLEAD_API_KEY in your environment (find the key under Settings -> API in the SmartLead app). No OAuth, no login flow.

Run

smartlead-pp-cli doctor

to verify setup.

SmartLead通过作为api_key查询参数传递的API密钥进行认证。在环境变量中设置SMARTLEAD_API_KEY（可在SmartLead应用的Settings -> API中找到密钥）。无需OAuth或登录流程。

运行

smartlead-pp-cli doctor

验证设置是否正确。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
bash
```
smartlead-pp-cli campaigns list --agent --select id,name,status
```
Previewable —
```
--dry-run
```
shows the request without sending
Offline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag
Explicit retries — use
```
--idempotent
```
only when an already-existing create should count as success, and
```
--ignore-missing
```
only when a missing delete target should count as success

在任何命令后添加

--agent

，等效于：

--json --compact --no-input --no-color --yes

。

可管道传输 — 标准输出为JSON，错误信息输出到标准错误
可过滤 —
```
--select
```
保留字段子集。点路径可深入嵌套结构；数组可遍历元素。对于冗长API，这是缩小上下文范围的关键：
bash
```
smartlead-pp-cli campaigns list --agent --select id,name,status
```
可预览 —
```
--dry-run
```
显示请求内容但不发送
离线友好 — 同步/搜索命令可在本地SQLite存储可用时使用该存储
非交互式 — 从不提示，所有输入均通过标志传递
显式重试 — 仅当已存在的创建操作应被视为成功时使用
```
--idempotent
```
，仅当缺失的删除目标应被视为成功时使用
```
--ignore-missing
```

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:

json

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse

.results

for data and

.meta.source

to know whether it's live or local. A human-readable

N results (live)

summary is printed to stderr only when stdout is a terminal AND no machine-format flag (

--json

--csv

--compact

--quiet

--plain

--select

) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.

从本地存储或API读取数据的命令会将输出包装在来源信封中：

json

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析

.results

获取数据，

.meta.source

可了解数据是来自实时API还是本地镜像。仅当标准输出为终端且未设置任何机器格式标志（

--json

、

--csv

、

--compact

、

--quiet

、

--plain

、

--select

）时，才会将人类可读的

N results (live)

摘要打印到标准错误；管道传输/Agent消费和显式格式运行时，标准输出仅为纯JSON。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:

smartlead-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
smartlead-pp-cli feedback --stdin < notes.txt
smartlead-pp-cli feedback list --json --limit 10

Entries are stored locally at

~/.smartlead-pp-cli/feedback.jsonl

. They are never POSTed unless

SMARTLEAD_FEEDBACK_ENDPOINT

is set AND either

--send

is passed or

SMARTLEAD_FEEDBACK_AUTO_SEND=true

. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

当您（或Agent）发现此CLI存在问题时，可记录反馈：

smartlead-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
smartlead-pp-cli feedback --stdin < notes.txt
smartlead-pp-cli feedback list --json --limit 10

反馈条目存储在本地

~/.smartlead-pp-cli/feedback.jsonl

文件中。除非设置了

SMARTLEAD_FEEDBACK_ENDPOINT

且传递了

--send

或设置

SMARTLEAD_FEEDBACK_AUTO_SEND=true

，否则反馈内容不会被POST发送。默认行为仅存储在本地。

请记录让您感到意外的内容，而非提交bug报告。简短、具体、单行描述：这是最有价值的部分。

Output Delivery

输出交付

Every command accepts

--deliver <sink>

. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename)
`webhook:<url>`	POST the output body to the URL ( `application/json` or `application/x-ndjson` when `--compact` )

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

每个命令都接受

--deliver <sink>

参数。输出会发送到指定的sink，同时（或替代）输出到标准输出，因此Agent无需手动管道即可路由命令结果。支持三种sink：

Sink	效果
`stdout`	默认；仅输出到标准输出
`file:<path>`	原子性地将输出写入 `<path>` （先写入临时文件再重命名）
`webhook:<url>`	将输出体POST到指定URL（当使用 `--compact` 时为 `application/json` 或 `application/x-ndjson` 格式）

未知的协议会被拒绝，并返回结构化错误，列出支持的协议类型。Webhook失败会返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

smartlead-pp-cli profile save briefing --json
smartlead-pp-cli --profile briefing campaigns list
smartlead-pp-cli profile list --json
smartlead-pp-cli profile show briefing
smartlead-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults.

agent-context

lists all available profiles under

available_profiles

so introspecting agents discover them at runtime.

配置文件是一组保存的标志值，可在多次调用中重复使用。当定时Agent每次运行都使用相同配置调用同一命令时，可使用此功能——即HeyGen的“Beacon”模式。

smartlead-pp-cli profile save briefing --json
smartlead-pp-cli --profile briefing campaigns list
smartlead-pp-cli profile list --json
smartlead-pp-cli profile show briefing
smartlead-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件值；配置文件值优先于默认值。

agent-context

会在

available_profiles

下列出所有可用配置文件，以便自省Agent在运行时发现它们。

Exit Codes

退出码

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

代码	含义
0	成功
2	使用错误（参数错误）
3	资源未找到
4	需要认证
5	API错误（上游问题）
7	速率限制（请等待并重试）
10	配置错误

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
→ show
```
smartlead-pp-cli --help
```
output
Starts with
install
→ ends with
```
mcp
```
→ MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with
```
--agent
```
)

解析

$ARGUMENTS

：

为空、
help
或
--help
→ 显示
```
smartlead-pp-cli --help
```
输出
以
install
开头 → 若以
```
mcp
```
结尾 → MCP安装；否则 → 参见顶部的前提条件
其他情况 → 直接使用（以
```
--agent
```
标志执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

bash

claude mcp add smartlead-pp-mcp -- smartlead-pp-mcp

Verify:

claude mcp list

从此CLI已发布的公共库条目或预构建版本安装MCP二进制文件，然后注册：

bash

claude mcp add smartlead-pp-mcp -- smartlead-pp-mcp

验证：

claude mcp list

Direct Use

直接使用

Check if installed:
```
which smartlead-pp-cli
```
If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the

--agent

flag:

bash

smartlead-pp-cli <command> [subcommand] [args] --agent

If ambiguous, drill into subcommand help:
```
smartlead-pp-cli <command> --help
```
.

检查是否已安装：
```
which smartlead-pp-cli
```
若未找到，提供安装选项（参见顶部的前提条件）。
将用户查询与上述“独特功能”和“命令参考”中的最佳命令匹配。

使用

--agent

标志执行：

bash

smartlead-pp-cli <command> [subcommand] [args] --agent

若存在歧义，查看子命令帮助：
```
smartlead-pp-cli <command> --help
```
。