PixelLetter

当用户希望使用 PixelLetter 发送或测试信件/PDF/传真、查询 PixelLetter 账户信息，或围绕 PixelLetter 的 HTTPS API 构建工作流时，请使用本技能。

配置

1. 在 https://www.pixelletter.de 注册一个免费账户
2. 为账户充值（每封信件费用约为 €0.79–€1.99）
3. 通过环境变量提供凭据：

export PIXELLETTER_EMAIL="your@email.com"
export PIXELLETTER_PASSWORD="yourpassword"

或者使用密钥注入（例如 Proton Pass）：

PIXELLETTER_EMAIL='pass://Personal/Pixelletter/email' 
PIXELLETTER_PASSWORD='pass://Personal/Pixelletter/password' 
pass-cli run -- node scripts/pixelletter.mjs account

4. 首次运行请务必使用试运行（dry-run）模式——不实际寄送邮件，亦不产生费用。

安全规范

• PixelLetter 会实际投递纸质信件/传真，可能产生费用。
• 默认必须启用测试模式。除非用户明确确认收件人、文档/正文内容、选项及费用/投递意图，否则严禁执行正式发送操作。
• 切勿在技能代码或示例中硬编码凭据。请始终使用环境变量或密钥注入方式：
  • PIXELLETTER_EMAIL
  • PIXELLETTER_PASSWORD
• 不得在日志、试运行输出、Git 提交、截图或社区共享的示例中暴露凭据。
• 对于已排版完成的信件，优先使用 PDF 上传方式；仅在简单信件且由 PixelLetter 负责排版时，才使用纯文本模式。
• 将 API 返回的成功状态码 100 视为“传输已接受”，而非最终投递成功。PixelLetter 将后续通过电子邮件发送最终投递确认。

CLI 封装脚本

配套脚本：scripts/pixelletter.mjs

可在技能目录下直接运行，或传入完整脚本路径。

PIXELLETTER_EMAIL="..." PIXELLETTER_PASSWORD="..." 
node scripts/pixelletter.mjs account

试运行纯文本信件

node scripts/pixelletter.mjs send-text 
  --address-file /path/address.txt 
  --message-file /path/message.txt 
  --subject "Betreff" 
  --destination DE 
  --dry-run

测试模式下的 PDF 上传（安全，不实际投递）

PIXELLETTER_EMAIL="..." PIXELLETTER_PASSWORD="..." 
node scripts/pixelletter.mjs send-upload 
  --file /path/letter.pdf 
  --destination DE

正式投递

仅在获得用户明确确认后执行：

PIXELLETTER_ALLOW_REAL_SEND=true 
PIXELLETTER_EMAIL="..." PIXELLETTER_PASSWORD="..." 
node scripts/pixelletter.mjs send-upload 
  --file /path/letter.pdf 
  --destination DE 
  --production 
  --confirm-real-send

重要选项

• --action 1|2|3
  • 1 = 仅邮政信件（默认）
  • 2 = 仅传真
  • 3 = 邮政信件 + 传真
• 若选择动作 2 或 3，必须指定 --fax "+49 ..." 参数。
• 若选择邮政信件动作 1 或 3，必须指定 --destination DE。
• --location 1|2|3
  • 1 = 慕尼黑（默认）
  • 2 = 维也纳附近 Hausleiten
  • 3 = 汉堡
• --addoption：挂号信选项，以英文逗号分隔：
  • 27 = Einschreiben（挂号信）
  • 28 = Rückschein（回执），仅可与 27 组合使用
  • 29 = Eigenhändig（本人签收），仅可与 27 组合使用
  • 30 = Einschreiben Einwurf（挂号投入信箱），不可与其他选项组合

API 参考

如需了解接口端点详情及响应结构，请仅在必要时查阅 references/api.md。