---
name: agentpostage
description: Send PDFs as physical US mail with AgentPostage and check their status, balance, tracking or return receipts. Use for mailing letters such as bank disputes, gym cancellations, credit bureau requests, notices and completed forms.
---

# AgentPostage

Send a PDF, a US recipient address and a US return address. AgentPostage prints and mails it. A send request queues real, paid mail without an additional AgentPostage approval step. Use the document, addresses and mailing service authorized by the user. Do not invent a recipient, signature, supporting fact or legal deadline.

## Connect

Use the AgentPostage MCP tools if already connected. Otherwise use the CLI or HTTP API below. The owner creates a verified account, accepts the policies, creates an API key and adds funds at https://agentpostage.com/connect/ and https://agentpostage.com/billing/.

The CLI reads `AGENTPOSTAGE_API_KEY` from its process environment. If using a secret store, inject the key into that environment through the store's normal secret-injection mechanism. Never ask for a key in a chat message or print it. If absent, direct the owner to configure it. Keys can spend the account balance but cannot charge a card or manage other keys.

Full API reference and current pricing: https://agentpostage.com/llms.txt
Address schema, file requirements and errors: https://agentpostage.com/docs/

## Send a local PDF

With Node.js 22 or later, download the standalone CLI to the task's working directory. This download does not send mail.

```sh
curl -fsS https://agentpostage.com/agentpostage.mjs -o agentpostage.mjs
node agentpostage.mjs balance
node agentpostage.mjs price --pages 3 --service first_class
```

Save `sender.json` and `recipient.json` as objects with these fields:

```json
{
  "name": "Recipient name",
  "address_line1": "Street address",
  "address_line2": "Optional unit or suite",
  "city": "City",
  "state": "TX",
  "postal_code": "12345",
  "country": "US"
}
```

Use the user's real addresses, not these placeholders. Both recipient and return addresses are required. If either is missing from authorized context, ask for it before sending. Omit an unused `address_line2`. Address fields must be single-line printable ASCII. PDF contents can contain Unicode.

Choose one unique idempotency key for this intended letter and save it before sending. It must be 8–128 ASCII letters, digits, dots, colons, underscores or hyphens. Replace the example key below with that key.

```sh
node agentpostage.mjs send \
  --pdf letter.pdf \
  --sender sender.json \
  --recipient recipient.json \
  --service first_class \
  --idempotency-key UNIQUE_LETTER_KEY
```

Use `certified` for USPS tracking or `certified_return_receipt` for tracking plus an electronic return receipt. Neither guarantees legal adequacy or a delivery date. `first_class_flat` selects a flat envelope. `first_class_hse` adds a Homeowner Statement Enclosed endorsement.

Defaults are black-and-white, single-sided, white US letter paper. Add `--color color` for full color or `--duplex true` for double-sided printing. `--paper` and `--return-envelope` select the documented paper stocks and reply envelopes. Use `--help` or the API reference for the exact choices. Use the same options for price and send. First-Class and HSE allow 500 PDF pages, both Certified services 150, and explicit flats 75 single-sided or 150 double-sided. Source PDFs can be up to 10 MiB. The address coversheet is included and is not an additional customer PDF page.

To check an exact price without mailing or spending, use `price_letter` with the actual `page_count` and options, or the CLI `price` command. A new letter's returned `cost.total_cents` is its fixed price. A price check does not reserve a rate indefinitely. The send uses the current tariff and freezes its price when queued.

Without Node.js, use `curl` with `POST https://agentpostage.com/v1/letters`, Bearer authentication, the `Idempotency-Key` header, and multipart fields `pdf`, `sender`, `recipient` and optional print options. The read-only `POST /v1/price` accepts JSON with `page_count` and the same options, without addresses or a PDF.

## Report and follow up

Save the returned letter ID. `202` and `queued` mean the request is saved, not that the letter has been mailed.

```sh
node agentpostage.mjs get LETTER_ID
node agentpostage.mjs list --limit 20
node agentpostage.mjs cancel LETTER_ID
node agentpostage.mjs transactions --limit 20
node agentpostage.mjs billing
```

- On a timeout or uncertain response, reuse the SAME idempotency key, PDF, addresses, service and print options. A new key can send a duplicate letter.
- For `submission_unknown`, check the existing letter. Do not submit a replacement.
- `awaiting_funds` means funding is needed. Give the owner the billing link. Never obtain card details or an owner session cookie.
- Read `cost.total_cents` on the returned letter. Do not invent a price or treat a legacy null cost as free.
- Only a successful cancellation response confirms cancellation. Cancellation is unavailable once mailing authorization starts.
- First-Class ends at confirmed `mailed`, without individual delivery confirmation. Certified can reach `delivered`. A return receipt can arrive later.
- When `receipt_url` is available, download it with Bearer authentication. Stored documents expire 30 days after confirmed First-Class mailing, Certified delivery, cancellation or rejection. Pending mail is retained until resolved.

If the PDF is rejected with `unsupported_print_annotation`, export or print it to PDF and retry the corrected document only after confirming the rejected request did not enqueue. Do not silently omit pages or annotations.