# AgentPostage
> Send a PDF and US addresses in one API request to queue printing and physical mailing.

- Website: https://agentpostage.com/
- REST reference: https://agentpostage.com/docs/
- Pricing: https://agentpostage.com/docs/#pricing
- Print options: https://agentpostage.com/docs/#print-options
- OpenAPI: https://agentpostage.com/openapi.json
- Create/revoke agent keys: https://agentpostage.com/connect/
- Owner billing: https://agentpostage.com/billing/
- MCP: https://agentpostage.com/mcp (HTTP MCP, Bearer key)
- Agent setup: https://agentpostage.com/docs/#agents
- Installable mail skill: https://agentpostage.com/skills/agentpostage/SKILL.md
- Private ChatGPT GPT Actions schema: https://agentpostage.com/chatgpt-actions.json
- ChatGPT instructions: https://agentpostage.com/chatgpt-instructions.txt
- Public integration repository (skill, Codex plugin and CLI): https://github.com/ctxrs/agentpostage
- Terms: https://agentpostage.com/terms/
- Privacy Policy: https://agentpostage.com/privacy/

The owner must create an account, verify email, accept the current Terms and acknowledge the Privacy Policy before creating keys, funding or sending. Owners sign in at /connect/ with a six-digit code sent by email. Direct them to /connect/?next=billing when funding is needed. Agent Bearer keys are separate from owner sign-in. Never collect owner passwords, verification codes or session cookies.

## Send
POST /v1/letters with Authorization: Bearer $AGENTPOSTAGE_API_KEY and required Idempotency-Key.
Multipart: pdf file, sender and recipient as JSON strings, optional service/color/duplex/paper/return_envelope. Multipart duplex is the string true or false.
JSON: pdf_base64, sender and recipient objects, optional service/color/duplex/paper/return_envelope. JSON duplex is a boolean.
Address fields: name, address_line1, optional address_line2, city, state, postal_code, country:"US".
Service: first_class (default), certified (tracking without a return receipt), certified_return_receipt, first_class_flat, first_class_hse (Homeowner Statement Enclosed endorsement).
Print defaults: color black, duplex false, paper white, return_envelope none.
color: black or color.
duplex: false or true.
paper: white, yellow, blue, green, orange, red, ivory, perforated, statement, check_blue, check_red, check_green, coupon.
return_envelope: none, right_window, left_window, small, coupon_pack. All reply envelopes are unstamped.
Specialty paper needs a correctly laid-out PDF. Check stock prints supplied artwork without issuing a payment or inserting bank details.
An authenticated POST /v1/letters requests physical sending. No prepare/approve/send sequence.
202 returns a saved, queued letter. Keep its id. Retry identical content with the SAME idempotency key.
A new key creates a new send. Do not generate a fresh one after a timeout.
Idempotency keys: 8–128 ASCII letters, digits, dots, colons, underscores or hyphens.

## Agent setup
OpenClaw and Hermes Agent: install SKILL.md in the client's skills directory, or configure native remote MCP. The skill uses the CLI/API with shell access. See /docs/#agents for exact commands and environment setup.
Codex: codex mcp add agentpostage --url https://agentpostage.com/mcp --bearer-token-env-var AGENTPOSTAGE_API_KEY
Claude Code: claude mcp add --scope user --transport http agentpostage https://agentpostage.com/mcp --header 'Authorization: Bearer ${AGENTPOSTAGE_API_KEY}'
Cursor: remote URL plus Authorization header Bearer ${env:AGENTPOSTAGE_API_KEY} in mcpServers. Environment must be available to the running app.
ChatGPT: a private custom GPT with Actions and Bearer API-key authentication, not the native MCP connector. Import /chatgpt-actions.json. Keep visibility Only me, because other GPT users could spend your balance.
ChatGPT POST /v1/chatgpt/letters takes {idempotency_key,openaiFileIdRefs,sender,recipient,service?,color?,duplex?,paper?,return_envelope?}.
openaiFileIdRefs is exactly one PDF reference. The Actions schema declares string items but ChatGPT supplies runtime objects {id,name,mime_type,download_link}.
Only HTTPS files.oaiusercontent.com attachment downloads are accepted, without redirects, up to 10 MiB and 10 seconds. Signed URLs are not stored.
Expired attachment: read a known letter ID first, or refresh the same PDF and retry with the SAME key, bytes, addresses, service and print options. The adapter uses the ordinary API idempotency and queue.

## Read and cancel
GET /v1/letters and GET /v1/transactions: limit 1–50 (default 20), cursor from next_cursor. Null ends pagination.
GET /v1/letters/{id}: status, cost, evidence, source_sha256, pdf_sha256, pdf_url, receipt_url.
POST /v1/letters/{id}/cancel: before authorization starts. Successful response confirms cancellation.
GET /v1/letters/{id}/pdf: authenticated print PDF, no provider coversheet. 410 after retention deletion.
GET /v1/letters/{id}/receipt: authenticated Certified return-receipt PDF when available. 410 after retention deletion.
receipt_url is null until evidence.return_receipt_available is true. A receipt can arrive after delivered status.
GET /v1/balance: available_cents, reserved_cents, debt_cents, dispatch_available, currency.
GET /v1/me: account identity and balance.
GET /v1/billing/link: owner billing URL.

## Status and money
States: queued, preauthorizing, awaiting_funds, authorizing, accepted, mailed, delivered, cancelled, rejected, submission_unknown.
accepted does not mean mailed or delivered. Use actual provider evidence. Do not infer receipt.
submission_unknown is unresolved: do not submit a replacement.
New letters return cost:{total_cents,currency:"USD"} immediately, fixed when queued. pricing_version identifies the tariff. Legacy letters keep prior pricing and can have a null cost until priced.
POST /v1/price with JSON {page_count,service?,color?,duplex?,paper?,return_envelope?} returns an exact price without creating a letter, reserving money or sending mail. No Idempotency-Key, addresses or PDF. Authentication required, current terms acceptance not required. Browser owner requests need the same-origin Origin header.
Tariff: 2026-09-17-retail. Prices are in USD cents. Page limits count customer PDF pages.

| Service | First PDF page (cents) | Single-sided page limit | Duplex page limit |
| --- | ---: | ---: | ---: |
| first_class | 400 | 500 | 500 |
| certified | 1200 | 150 | 150 |
| certified_return_receipt | 1500 | 150 | 150 |
| first_class_flat | 600 | 75 | 150 |
| first_class_hse | 400 | 500 | 500 |

Each extra PDF page costs 30 cents. Color adds 30 cents for every PDF page, including the first. Duplex uses the same per-PDF-page rate. Nonwhite paper adds 10 cents per document sheet (ceil(page_count/2) for duplex). A reply envelope costs 50 cents, or 150 cents for coupon_pack (12 envelopes). Address coversheet, printing, outgoing envelope and US postage are included. The coversheet adds no page or sheet charge. No extra weight surcharge.

Example POST /v1/price request:
```json
{"page_count":3,"color":"color","duplex":true,"paper":"blue","return_envelope":"small"}
```
Response:
```json
{"total_cents":620,"currency":"USD","pricing_version":"2026-09-17-retail","page_count":3,"service":"first_class","color":"color","duplex":true,"paper":"blue","return_envelope":"small","address_coversheet":true}
```

A price check does not reserve a future rate. Sending authorizes the current tariff, without a separate quote approval.
Minimum funding/recharge payment: $10. There is no subscription.
Confirmed funds constrain sending. No per-key spending allowance.
Only the owner can manage keys, top up or consent to saved-card automatic recharge.
Recharge starts disabled. Initial amount $25 when available balance is below $5.
Return from Stripe does not prove payment. Wait for verified account balance.
When human billing action is required, return the billing link. Never obtain owner cookies or card data.

## MCP tools
price_letter: {page_count,service?,color?,duplex?,paper?,return_envelope?}
send_letter: {idempotency_key,pdf_base64,sender,recipient,service?,color?,duplex?,paper?,return_envelope?}
get_letter: {id}
list_letters: {limit?,cursor?}
cancel_letter: {id}
get_balance: {}
list_transactions: {limit?,cursor?}
get_billing_link: {}
MCP returns the same structured resource/error as REST. REST is authoritative.

## CLI download and use
Requires Node.js 22 or later. Download https://agentpostage.com/agentpostage.mjs:

curl -fsS https://agentpostage.com/agentpostage.mjs -o agentpostage.mjs
node agentpostage.mjs --help
node agentpostage.mjs price --pages 3 --service first_class --color color --duplex true
node agentpostage.mjs send --pdf letter.pdf --sender sender.json --recipient recipient.json --idempotency-key letter-2026-001
Optional --service, --color, --duplex true|false, --paper and --return-envelope use the values above. Address files contain the same JSON objects as REST.
Commands: balance, list, get ID, cancel ID, transactions, billing.
AGENTPOSTAGE_API_KEY is required. AGENTPOSTAGE_BASE_URL defaults to https://agentpostage.com.
Omitting --idempotency-key generates one and prints it to stderr BEFORE sending. Preserve it for retries.
JSON results go to stdout. The billing command returns the owner's billing URL.

## File boundaries
PDF only. 10 MiB source and 20 MiB normalized print PDF.
Document page limits are listed with the tariff above. PDFs exceeding a service page limit return HTTP 400 before storage or charging.
These are supported printing limits, not account or key spending limits.
Ordinary scanned/image-rich/font-embedded/Unicode PDFs retain their visual content.
Forms and printable annotations require a saved normal appearance in the PDF.
A printable annotation without one returns HTTP 400 unsupported_print_annotation. It is not silently dropped.
Export or print the document to PDF, then upload that copy.
Non-US-letter pages fit onto US letter paper. Encrypted, corrupt and empty PDFs are rejected.
Addresses are single-line US addresses with printable ASCII fields. The PDF itself supports Unicode.
Default black-and-white, single-sided white paper. Color, duplex and other stocks use the optional fields above. An included address coversheet is added for mailing and not counted as a customer PDF page.
The standard /v1/letters endpoint does not fetch external PDF URLs. Only the ChatGPT attachment adapter fetches the restricted OpenAI file host above. No plain text drafting or international mail.
PDFs, stored return receipts and addresses: 30 days after confirmed mailing for any First-Class variant, or delivery for either Certified variant. print_options is null after document deletion.
Cancellation or rejection starts the 30-day period for either service.
First-Class status remains mailed. It does not confirm delivery.
Documents for pending mail, including mailed Certified letters, awaiting_funds and submission_unknown, remain stored until resolved.
Billing/accounting metadata are retained separately as needed. Payment issues do not extend document retention.
Keep needed evidence before retention ends.
No legal advice, guaranteed legal compliance, dispute outcomes, delivery dates or service-of-process guarantees.

## Errors
JSON: {"error":{"code":"…","message":"…","next_action":"…"}}. next_action is optional.
400 invalid input. 401/403 authentication/permission. 404 unavailable resource. 409 conflicting input/state. 410 expired document retention. 413 size limit. 5xx possibly uncertain result.
On network/5xx errors read known resources and retry with the original idempotency key.