postscanmail

Use when working with PostScanMail virtual mailbox API — fetching mail items, managing auto-scan rules, or checking for incoming physical mail. Also use when integrating a CMRA virtual mailbox.

Model	Source
sonnet	pack: mail

Full Reference

┏━ 🔧 postscanmail ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ PostScanMail — virtual mailbox, scan, forward ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

postscanmail

Virtual mailbox management via PostScanMail API — listing mail items, managing auto-scan rules, polling for new mail.

Quick Reference

Item	Value
API base	https://api.postscanmail.com/api/account-docs/v2
Auth	x-api-key header
Sandbox	None — all requests hit production
Rate limit	250 req/window; Retry-After: 60 on 429
Pagination	Page-based, 20 items/page fixed (no per_page param)
Date filtering	Client-side only — no server-side date params
v1 status	Deprecated — returns 410 Gone

Reference Index

Doc	What’s inside
reference/items.md	GET /items, response shape, empty mailbox edge case, PDF download
reference/rules.md	GET/PUT auto-scan rules endpoints, rule meanings, request/response shapes
reference/integration.md	Polling strategy, rate limit handling, error patterns, security checklist

Common Operations

List mail items (page 1):

curl "https://api.postscanmail.com/api/account-docs/v2/items?page=1" \
  -H "x-api-key: $POSTSCAN_API_KEY"

List items sorted oldest-first:

curl "https://api.postscanmail.com/api/account-docs/v2/items?page=1&sort_order=asc" \
  -H "x-api-key: $POSTSCAN_API_KEY"

Get auto-scan rules:

curl "https://api.postscanmail.com/api/account-docs/v2/user-defined-rules/system-user-defined-rules" \
  -H "x-api-key: $POSTSCAN_API_KEY"

Update a rule:

curl -X PUT "https://api.postscanmail.com/api/account-docs/v2/user-defined-rules/update-system-user-defined-rule" \
  -H "x-api-key: $POSTSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rule_id": 42, "enabled": true}'

Key Gotchas

• No sandbox — every request hits live production data
• Empty mailbox trap — data array contains a string message instead of objects when mailbox is empty; guard before accessing item fields
• No per_page — always 20 per page, pagination is the only way to get more
• No server-side filtering — filter by date/status client-side after fetching

Common Mistakes

Mistake	Fix
Accessing data[0].mail_id on empty mailbox	Guard: if (!Array.isArray(data) || typeof data[0] === 'string') return []
Using v1 endpoints	Switch to v2 — v1 returns 410 Gone
Expecting per_page param to work	It’s ignored; page size is always 20
Filtering by date server-side	Fetch pages and filter client-side
Logging raw API key	Redact in all log output