端到端 B2B 触达工具集，整合批量冷邮件、全球短信、Google Maps 商户采集与联系方式校验于一体。支持企业批量冷邮件群发与全球短信群发（双向可回复），并监控发送、送达、打开、回复等完整送达状态；按国家、地区、半径、行业与关键词采集Google Maps 商户数据，批量获取商家名称、地址与联系方式；触达前校验手机号（座机、手机、是否注册WhatsApp）、邮箱与域名，降低退信率、清洗 CRM 联系人列表。帮助出口商、贸易商、采购代理与全球销售团队开展跨境触达活动--采集、校验、触达、监控一站式完成，

B2B 触达（Outreach）

聚合技能：邮件 + 短信 + 地图商户采集 + 联系方式校验。11 个脚本，扁平结构（脚本数少，直接列出，不加索引层）。

概览

四大能力组：

运行脚本

环境准备

1. 检查 Python：python --version
2. 安装依赖：pip install -r requirements.txt

脚本目录：scripts/*.py

重要：始终用直接调用方式，如 python scripts/mail_send.py。不要用 cd scripts && python mail_send.py 这类 shell 复合命令。

脚本

邮件

mail_send.py - 发送邮件

向一个或多个收件人发送邮件。

• 参数：见 Email Send API

python scripts/mail_send.py \
  --subject "Test Email" \
  --content "This is the email content" \
  --emails '["recipient@example.com"]'

mail_task_list.py - 邮件任务列表

查看邮件任务，支持时间范围/状态过滤。

• 参数：见 Email Task List API

python scripts/mail_task_list.py --page_no 1 --page_size 10

mail_task_record_list.py - 邮件任务记录

查看某邮件任务的送达明细记录。

• 参数：见 Email Task Record List API

python scripts/mail_task_record_list.py --task_id 1496 --page_no 1 --page_size 10

短信

sms_send.py - 发送短信

向手机号发送短信；--channel_type 1 开启双向（可回复）模式。

• 参数：见 SMS Send API

python scripts/sms_send.py \
  --content "This is SMS content" \
  --phones '["13800138000"]'

sms_task_list.py - 短信任务列表

• 参数：见 SMS Task List API

python scripts/sms_task_list.py --page_no 1 --page_size 10

sms_task_record_list.py - 短信任务记录

• 参数：见 SMS Task Record List API

python scripts/sms_task_record_list.py --task_id 1496 --page_no 1 --page_size 10

地图商户

merchants_search.py - 商户搜索

按关键词 + 地点搜索 Google Maps 商户。两种模式：国家/省/市搜索，或附近搜索（经纬度 + 半径，用 geoDistance）。

• 参数：见 Merchants Search API

python scripts/merchants_search.py \
  --params '{"keywords":["restaurant"],"countryCodes":["BR"]}' \
  --query_count 100

geography_list.py - 地理列表

获取国家/省/市 ID，用于构造 merchants_search 参数。

python scripts/geography_list.py --type country
python scripts/geography_list.py --type province --country_id 1
python scripts/geography_list.py --type city --country_id 1

• 国家列表：country-list | 省份列表：province-list | 城市列表：city-list

联系方式校验

phone_validity_check.py - 手机号校验

校验手机号有效性、类型及 WhatsApp 注册状态。

• 参数：见 Phone Validity API

python scripts/phone_validity_check.py --phones "+8613812345678 +14155551234"

email_validity_check.py - 邮箱校验

校验邮箱地址有效性/可送达性。

• 参数：见 Email Validity API

python scripts/email_validity_check.py --emails "a@example.com b@example.com"

domain_validity_check.py - 域名校验

校验域名有效性与安全性。

• 参数：见 Domain Validity API

python scripts/domain_validity_check.py --domains "example.com foo.org"

核心工作流：触达前先校验

本聚合技能的标志性工作流（清洗 -> 触达 -> 监控）：

1. 收集联系方式 - 从 CRM 导出，或用 merchants_search（地图）采集，或由 b2b-lead-generation（决策人查询）提供。
2. 校验清洗 - 跑 phone_validity_check / email_validity_check / domain_validity_check 剔除无效联系方式。（减少浪费的发送与费用。）
3. 触达 - mail_send（冷邮件）和/或 sms_send（全球短信，双向可回复）。
4. 监控送达 - mail_task_list / sms_task_list -> *_task_record_list 查看送达状态。

校验本身也收费 -- 但远比发给无效联系方式划算。先告知用户校验费用。

API 密钥与充值

本技能需要 API 密钥，存储在 ~/.upkuajing/.env：

cat ~/.upkuajing/.env

UPKUAJING_API_KEY=your_api_key_here

未设置 API 密钥

先检查 ~/.upkuajing/.env 是否有 UPKUAJING_API_KEY。若没有，提示用户选择：

1. 用户已有：用户提供（手动写入 ~/.upkuajing/.env）
2. 用户没有：用 auth.py --new_key 申请（自动保存到 ~/.upkuajing/.env）

等待用户选择。

账户充值

当 API 返回余额不足时：

1. 创建充值订单（auth.py --new_rec_order）
2. 把支付页面 URL 发给用户，引导其打开并支付；用户确认成功后再继续。

获取账户信息

python scripts/auth.py --account_info

新申请的密钥需在 跨境魔方开放平台 注册绑定。

计费

发送/搜索/校验调用均收费；任务列表与记录列表查询免费。

最新定价：访问 详细价格说明，或运行：

python scripts/auth.py --price_info

（返回全部接口定价 -- 聚合版 auth.py 优先拉取全量定价列表，必要时回退到按原始技能名逐一查询。）

计费规则（概要）

• 邮件/短信发送：按发送请求计费，费用随收件人数量递增。
• 商户搜索：按调用次数计费，每次返回最多 100 条 -> 调用次数 = ceil(query_count / 100)。
• 手机/邮箱/域名校验：按校验次数计费（每个号码/邮箱/域名）。
• 免费：geography_list；所有 *_task_list / *_task_record_list。
• 各接口计费细则见对应 references/-api.md。

计费确认原则

任何收费操作必须先告知用户并在单独的消息中等待明确确认，不得在通知的同一消息中执行。 当 query_count 超过一页时，先告知用户预计调用次数。

错误处理

• API 密钥无效/不存在：检查 ~/.upkuajing/.env 中的 UPKUAJING_API_KEY
• 余额不足：引导用户充值
• 参数无效：必须先查 references/ 下对应 API 文档，从文档获取正确参数名/格式，不要猜测

API 文档参考

邮件

• email-send | email-task-list | email-task-record-list

短信

• sms-send | sms-task-list | sms-task-record-list

地图商户

• merchants-search | country-list | province-list | city-list

校验（加 validity- 前缀，与 email-send 等营销文档区分）

• validity-phone | validity-email | validity-domain

注意事项

• 邮件/短信发送为同步提交、异步送达：API 立即返回；通过任务记录查看 status。邮件状态：0-待发送 1-发送中 2-发送完成。短信状态：1-发送中 2-发送完成 3-失败 4-部分成功。
• task_data/ 按 UUID 子目录存放结果。
• 国家代码使用 ISO 3166-1 alpha-2（如 CN、US、BR）。地图搜索关键词/行业须用英文。
• 所有平台文件路径使用正斜杠。
• 禁止输出技术参数格式：回复中把代码式参数转为自然语言。
• 不要估算每次调用费用 -- 用 auth.py --price_info 获取准确定价。
• 不要猜测参数名 -- 先读 references/-api.md。

关联技能

其他可能有用的 UpKuaJing 技能：

• b2b-lead-generation - 海关贸易情报、全球企业深度背调、LinkedIn 职业人脉（找待触达的线索）
• upkuajing-email-tool - 独立的邮件发送与任务跟踪
• upkuajing-sms-tool - 独立的短信发送与任务跟踪
• upkuajing-map-merchants-search - 独立的 Google Maps 商户采集
• upkuajing-contact-info-validity-check - 独立的联系方式校验（phone/email/domain）
• upkuajing-customs-trade-company-search（= upkuajing-trade-company-search）- 搜索有真实海关贸易记录的公司
• upkuajing-company-people-search（= upkuajing-global-company-people-search）- 快速浅层查公司/人 + 联系方式