通过PostGrid发送CRM传统邮件

使用此技能可从CRM联系人中开展定向直邮推广。

工作流程

1. 1. 选择数据源：ghl、fub或预导出的联系人JSON文件。
2. 提取联系人并标准化为通用架构。
3. 筛选出具有可邮寄地址的记录。
4. 构建个性化消息内容。
5. 向PostGrid提交任务（letters信件或postcards明信片），支持试运行模式。
6. 返回发送摘要，包含每个联系人的成功/失败状态。

脚本

• - scripts/crmpostgridmailer.py

• - scripts/postgrid_api.py

环境变量

• - GHLAPIKEY：GHL API密钥/令牌。
• GHLBASEURL（可选）：默认为https://services.leadconnectorhq.com。
• FUBAPIKEY：Follow Up Boss API密钥。
• FUBBASEURL（可选）：默认为https://api.followupboss.com/v1。
• POSTGRIDAPIKEY：PostGrid API密钥。
• POSTGRIDBASEURL（可选）：默认为https://api.postgrid.com/print-mail/v1。

常用命令

列出此技能中包含的完整PostGrid端点目录：

bash
python3 scripts/postgrid_api.py list-endpoints

调用已编录的PostGrid端点：

bash
python3 scripts/postgrid_api.py call contacts.list

直接调用任意PostGrid端点（完整文档覆盖回退）：

bash
python3 scripts/postgrid_api.py call-raw GET /letters \
--base-url https://api.postgrid.com/print-mail/v1

将FUB联系人标准化为JSON：

bash
python3 scripts/crmpostgridmailer.py fetch \
--provider fub \
--limit 200 \
--output /tmp/fubcontactsnormalized.json

将GHL联系人标准化为JSON：

bash
python3 scripts/crmpostgridmailer.py fetch \
--provider ghl \
--location-id $GHLLOCATIONID \
--limit 200 \
--output /tmp/ghlcontactsnormalized.json

试运行PostGrid负载生成：

bash
python3 scripts/crmpostgridmailer.py send \
--contacts-file /tmp/ghlcontactsnormalized.json \
--from-json-file references/examplesenderus.json \
--html-template-file references/examplelettertemplate.html \
--mail-route letters \
--dry-run

一步完成提取+发送：

bash
python3 scripts/crmpostgridmailer.py run \
--provider fub \
--limit 100 \
--from-json-file references/examplesenderus.json \
--html-template-file references/examplelettertemplate.html \
--mail-route letters \
--output /tmp/mailsendsummary.json

从原始地址+内容发送一次性邮件：

bash
python3 scripts/crmpostgridmailer.py one-off \
--to-name Jane Seller \
--to-address1 742 Evergreen Terrace \
--to-city Springfield \
--to-state IL \
--to-postal-code 62704 \
--from-json-file references/examplesenderus.json \
--content-text Hi Jane,\n\nId love to send you a fresh home valuation this week.\n\nBest,\nDaniel \
--mail-route letters \
--dry-run

使用其他GHL/FUB技能导出的JSON：

bash
python3 scripts/crmpostgridmailer.py run \
--contacts-file /tmp/contactsfromother_skill.json \
--from-json-file references/examplesenderus.json \
--html-template-file references/examplelettertemplate.html \
--mail-route letters

数据契约

标准化联系人结构：

• - id
• firstname
• lastname
• fullname
• email
• phone
• address1
• address2
• city
• state
• postalcode
• country
• tags
• raw

默认情况下，缺少address1、city、state或postal_code的联系人将被跳过。

集成说明

• - 如果已有专门的GHL/FUB技能并返回联系人JSON，请使用--contacts-file参数传入该文件，跳过API提取。
• 如果API发生变化，请在scripts/crmpostgridmailer.py中调整映射候选字段，无需重写工作流程。
• 当账户特定的PostGrid路由与默认值不同时，使用--postgrid-route参数。

PostGrid安全措施

• - 首先使用--dry-run检查生成的负载。
• 首次实际运行时保留--max-send参数（例如--max-send 10）。
• 使用--description参数包含清晰的营销活动元数据。

有关路由/标头假设和覆盖策略，请参阅references/postgrid-notes.md。