用途:postage 技能通过 AgentPostage 把已有的 PDF 作为实体信件寄往美国地址,使用美国寄件人与收件人地址。寄送会直接排队真实的付费邮件,不再额外走 AgentPostage 审批步骤;但仅要求起草或询价并不构成寄送授权,需要用户请求或既有授权覆盖本次寄送及其选项。
连接方式:已连接时优先使用 AgentPostage MCP 工具;否则使用随附的 scripts/agentpostage.mjs(需 Node.js 22+)或 HTTP API,脚本路径按本技能目录解析,CLI 无包依赖。也可从 https://agentpostage.com/agentpostage.mjs 下载独立 CLI 并先审阅。正常使用时不要设置 AGENTPOSTAGE_BASE_URL,不要把密钥或文档重定向到其他来源,除非所有者明确授权。人类所有者需在 https://agentpostage.com/connect/ 注册、创建密钥,在 https://agentpostage.com/billing/ 充值;代理环境需提供 AGENTPOSTAGE_API_KEY,切勿在对话中索取密钥、打印密钥或获取所有者 cookie 与卡信息。密钥可动用账户余额,但不能管理密钥或直接扣卡;若开启自动充值,寄送可能触发充值。
主要能力与选项:地址字段包括 name、address_line1、可选 address_line2、city、两字母 state、postal_code 和 country("US"),须为单行可打印 ASCII;PDF 本身支持 Unicode。默认 first_class,certified 增加追踪,certified_return_receipt 增加追踪和电子回执,first_class_flat 用于不折叠寄送,first_class_hse 增加 Homeowner Statement Enclosed 背书。默认黑白、单面白纸、无回邮信封,回邮信封不带邮票。均不保证法律充分性或送达日期。
使用方式与限制:源 PDF 不超过 10 MiB;First-Class/HSE 允许 500 文档页,两种 Certified 为 150 页,显式 flats 为 75 单面或 150 双面;附带封面不计为客户页。加密、损坏、空白 PDF 会被拒绝。寄送前先确定并保留唯一幂等键(8–128 个 ASCII 字母、数字、点、冒号、下划线或连字符)。查询价格用 price_letter 传 page_count 与拟用选项,不会发送、存储 PDF 或预留资金;寄送在排队时冻结当前价格。MCP send_letter 需 idempotency_key、实际 PDF 字节的 pdf_base64、sender、recipient 及可选 service、color、duplex、paper、return_envelope;不得编造 base64 或使用外部 PDF URL。CLI 示例:node "<skill-directory>/scripts/agentpostage.mjs" send --pdf letter.pdf --sender sender.json --recipient recipient.json --service first_class --idempotency-key UNIQUE_LETTER_KEY(将示例键替换为保留的键,并与询价时所选打印选项一致)。也可用 HTTP:POST https://agentpostage.com/v1/letters,支持 multipart pdf、sender、recipient 或 JSON pdf_base64 与地址对象,需 Bearer 认证与 Idempotency-Key。
状态与恢复:保存返回的 letter ID,报告实际状态与 cost.total_cents;202 与 queued 表示已保存待发,不代表已寄出;cost 为旧版 null 不代表免费。超时或 5xx 后先读取已知 letter ID 或列出信件;重试须复用同一幂等键、PDF 字节、地址、服务与打印选项,新键可能造成重复寄件;409 可能表示输入变化或状态冲突,应检查而非换键。submission_unknown 时检查已有信件,不要提交替代件。awaiting_funds 时返回账单链接,浏览器付款返回不代表已到账。accepted 不代表已寄出或送达;First-Class 止于确认已寄出,Certified 可到已送达。cancel_letter 在授权开始前可取消,仅成功响应才确认取消。可用 Bearer 认证获取 receipt_url,否则让所有者在已登录浏览器打开该路径。留存期为确认 First-Class 寄出、Certified 送达、取消或拒绝后 30 天,需在此之前保存 PDF 与回执。后续工具包括 get_letter、list_letters、list_transactions、get_balance、get_billing_link 等,列表限制 1–50,next_cursor 为 null 结束分页。报价、端点字段、打印选项与限制详见 https://agentpostage.com/llms.txt 或 https://agentpostage.com/docs/,MCP 位于 https://agentpostage.com/mcp(Streamable HTTP + Bearer,非 OAuth)。