The short answer
A mailroom API connects physical-mail work to your software. For outbound letters, it lets a remote team prepare a PDF, review the recipient and price, then order printing and mailing without an office printer. IRIS handles individual outbound US letters and postcards; receiving and scanning incoming post requires an inbound mail service.
Which kind of mailroom API do you need?
Start with the physical task. Receiving an envelope, handing a parcel to a colleague, and sending a new letter need different services. An integration that reads scanned incoming mail will not necessarily print your outgoing PDF.
For example, PostScan Mail documents access to received mail and scanned documents. Parcel Tracker describes integrations for parcel intake and recipient notifications. IRIS provides the outbound printing and mailing step for a finished letter or postcard. Check each provider’s current scope before building around it.
| Your task | What the service needs to do |
|---|---|
| Receive business post while working remotely | Provide an inbound mail address, scanning, and access or forwarding controls. IRIS does not receive incoming mail. |
| Manage parcels at a staffed office or building | Record intake, notify the recipient, and record handoff. IRIS does not manage packages. |
| Mail a finished PDF from your business software | Accept the PDF and both addresses, quote printing and postage, and return a mailing order. This is the outbound workflow covered here. |
Define who owns a letter before choosing the tooling
Distributed teams often have an informal mailroom: someone receives a PDF in chat, prints it at home, finds an envelope, and later confirms it was sent. The weak point is usually the handoff. A clearer process starts with a named owner, a complete document, a current address, and a visible review state.
For occasional mail, the IRIS website may be enough. An API integration becomes useful when your software already holds the documents and business records, or when your team repeatedly copies the same fields into a mailing screen. Start with the simplest workflow that keeps responsibility visible.
Separate preparation, review, and follow-up
These are responsibilities your team can assign; they are not claims about built-in IRIS team seats or an approval dashboard. Your own application or documented process can provide the shared queue.
| Responsibility | Practical output |
|---|---|
| Requester | Business purpose, source document, and intended recipient. |
| Preparer | Final PDF, complete addresses, and a quote. |
| Reviewer | Approval of the exact document, options, price, and authority. |
| Submission service | One persisted intent and resulting orderId. |
| Operations owner | Status follow-up, credit availability, and exceptions. |
Connect your review queue to the mailing API
Consider a customer who requests a paper copy of a service confirmation. Your application generates the PDF and puts it in a review queue. A colleague checks the document, recipient, return address, and price before the submission service creates the mailing.
Use a verified developer account with prepaid credits and keep its credentials on your server. For preparation, explicitly select documents:write and mailings:read; add account:read if the service checks the balance. Keep mailings:write with the approved submission step. Newly created keys are not read-only by default.
- Prepare the final US Letter PDF and both complete US addresses. Sender and recipient each need a person or company name, street address, city, state, and ZIP code.
- Request POST /v1/uploads/presign, then PUT the PDF bytes to the returned uploadUrl using all returned uploadHeaders. Keep the IRIS bearer token out of that storage upload.
- Register the uploaded file with POST /v1/documents. Save the returned document ID and fingerprint with the source business record.
- Call POST /v1/mailings/quote with the document, sender, recipient, and print options. Show the price in dollars from its integer US cents value. A quote does not spend credits or reserve the price.
- Have the reviewer approve the final PDF, both names and addresses, options, price, and purpose. Save that approved payload and one Idempotency-Key before calling POST /v1/mailings. Submission recalculates the price, spends credits, and starts fulfillment; it is not a draft-save endpoint.
- Save the returned orderId and readable orderNumber. Use GET /v1/mailings/{orderId} for the current order state and available tracking; keep the document ID and postal tracking number in their own fields.
Handle timeouts and missing details without sending twice
A network timeout does not tell you whether a paid mailing was created. Keep the approved request and its idempotency key in durable storage so another worker can recover the same intent.
If the POST response is lost before you receive an order ID, repeat POST /v1/mailings with the original Idempotency-Key and unchanged payload. A completed replay returns the original order without another debit. Once you have the ID, read its current status with GET. The POST acknowledgement, including a replay, is not a live fulfillment-status report.
| What happened | What your workflow should do |
|---|---|
| The submission timed out | Recover with the original key and unchanged payload. Do not generate a new key just to retry. |
| A name, address field, or document is invalid | Show the field-level error to the preparer, correct the input, and obtain a fresh quote and review before submission. |
| The API returns 402 insufficient_credits | Ask the account owner to review the balance and add credits before resuming the approved workflow. |
| The API returns 409 or 429 | Investigate an idempotency conflict instead of cycling keys. For a rate limit, wait the Retry-After interval before retrying. |
| Tracking is empty or the order has not advanced | Keep the existing order and check its status. A missing tracking number is not evidence that no order exists. Escalate unclear or failed fulfillment to a person. |
Compare the complete workflow cost
A useful cost comparison includes staff handling time, printing supplies, postage, and the time spent correcting or tracing a mailing. Use your own measured handling time and labor assumption. Add the actual IRIS quote, plus any integration maintenance cost, to compare equivalent jobs.
For example, a spreadsheet can record minutes spent preparing a manual letter and minutes spent reviewing an API-prepared one. Multiply by your chosen hourly cost and compare the totals over a representative period. Label assumptions clearly. Avoid promising a fixed percentage saving before your team has measured its own process.
Pilot one document type
Choose one routine document, such as that requested paper service confirmation. Test preparation and error handling locally with fixtures before making a deliberately approved paid mailing. A key name or test document does not turn production submission into a sandbox.
Keep the shared queue, approval history, and business rules in your application. IRIS does not supply team approval seats, scheduled sending, mailing-list campaigns, or an inbound virtual office address through this API. For occasional letters, use the website and the same review checklist.
After the pilot, compare preparation time, address corrections caught before payment, and exceptions needing follow-up. Confirm that a colleague can recover a lost response and find the order record. Expand the workflow when those steps work reliably for your team.
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.
- IRIS API documentation and current limits
- IRIS OpenAPI contract
- PostScan Mail: inbound mail and scanning API
- Parcel Tracker: mailroom app integrations
Published by IRIS Postal Forms, operated by Great Lakes Computing Office LLC. Send a correction.