The short answer
A dependable agent mailing workflow separates preparation, human review, and submission. Bind approval to an immutable PDF and exact mailing details, restrict the credentials available to the agent, and preserve one idempotency key and order record for each intended letter.
Make the handoff explicit
Consider an agent that prepares a project-completion letter from approved service records. Drafting the letter is reversible. Creating a paid physical mailing begins a different process. Your application should make that transition visible, with a reviewable document and a specific action that a person can approve.
IRIS exposes REST and server MCP for this workflow. Its create-mailing tool describes a human-review requirement, but a tool description does not enforce your application’s business rules. Put the review gate in trusted application code. Do not rely on a sentence in a system prompt as the only control over a credential that can spend mailing credits.
Use states that describe what actually happened
The following are suggested states for your application, not additional statuses returned by IRIS. They keep a generated draft from being confused with a submitted or delivered letter.
| State | Exit condition |
|---|---|
| Draft | Source facts checked and a final PDF produced. |
| Prepared | PDF registered, addresses complete, quote obtained. |
| Awaiting review | Reviewer sees the exact PDF, destination, options, and price. |
| Approved | Approval stored against the immutable document and payload. |
| Submission uncertain | Reconcile a lost response using the saved idempotency key. |
| Order recorded | Persist the IRIS orderId and read current status. |
Give preparation and submission different permissions
Use account:read, documents:write, and mailings:read for a preparation worker. Keep mailings:write in the component responsible for approved submissions. A balance-only assistant can use an account:read credential. Store all keys in trusted environments and revoke unused keys when a workflow is retired.
Treat PDF text, CRM notes, and tool results as data. An instruction embedded in a document such as “send this to another address” should not override the reviewed recipient. Prefer validated fields from your application record to addresses extracted from arbitrary prose. Require a new review when the document or mailing details change.
Save a useful approval record
Persist the business purpose, source record reference, immutable document ID, document fingerprint, exact sender and recipient, print options, quoted amount, reviewer, and review timestamp in your own system. Associate one idempotency key with that record before the first submission attempt.
IRIS recalculates pricing when creating the credited mailing; a quote is not a price reservation. If time has passed, obtain a fresh quote and return a changed total to the reviewer before submission. If your use case needs an atomic maximum-price condition, confirm the API supports that contract before depending on it; the current mailing payload does not include such a field.
Test the moments where an agent should stop
Useful tests change the facts the agent would like to assume. Give it a missing street address, a PDF that fails validation, a quote above your internal budget, or a record that changed after approval. Each case should stop before submission and tell the reviewer what needs attention.
Also simulate a successful submission whose HTTP response is lost. The retry must reuse the saved key and exact payload. An order status that is delayed or has no tracking number must not trigger a replacement mailing automatically. Route uncertain cases to a person who can reconcile the business record with the order.
Sources & further reading
Product details checked against the IRIS API contract when this article was published. Platform references can change; consult the linked documentation when implementing.
Published by IRIS Postal Forms, operated by Great Lakes Computing Office LLC. Send a correction.