The short answer
A print and mail API lets your software submit a digital document for physical delivery. With IRIS, your application uploads a finished PDF, registers it, gets a quote, and creates one US mailing after a person reviews the document, addresses, price, and purpose.
Where a mailing API fits in your business
Imagine a small service company that already generates a PDF confirmation for each completed project. Most customers receive it electronically, but one customer requests a paper copy. The useful automation is the handoff: reuse the approved PDF and customer address, obtain a price, and let a staff member approve the mailing without retyping everything.
That is a good starting point for IRIS. It supports individual letters and postcards through REST and authenticated server MCP. Your application remains responsible for deciding why a document should be sent, generating its contents, and obtaining review. IRIS handles the supported mailing order after submission. A quote is a price calculation; it does not mail the document.
The six steps from PDF to mailing order
Keep each step explicit in your application. A document ID, a mailing order ID, and a postal tracking number identify different things. Store them in separate fields.
- Create and verify an IRIS developer account. Keep an account-bound API key in a trusted server environment and add prepaid mailing credits before submitting.
- Request a private upload with POST /v1/uploads/presign. Upload the PDF bytes to the returned URL using exactly the returned upload headers.
- Register the uploaded PDF with POST /v1/documents. Save the immutable document ID and its SHA-256 fingerprint.
- Send the document ID, sender, recipient, and print options to POST /v1/mailings/quote. Display the returned price in US cents as a currency amount.
- Have a person review the final PDF, both addresses, mailing options, price, and authority to send. Persist one idempotency key for that approved intent.
- Submit POST /v1/mailings with that saved Idempotency-Key. Save the returned orderId and read GET /v1/mailings/{id} for status and available tracking.
What to build around the API
A reliable integration needs a small operational record as well as an HTTP client. Start with one document type and one team before expanding.
| Your application | IRIS API |
|---|---|
| Source records, PDF generation, and document version | Private upload and validated document registration |
| Reviewer, approved recipient, and mailing intent | Server-calculated quote and credited order creation |
| Durable retry key and exception queue | Idempotent submission and account-owned order lookup |
| Customer communication and internal reporting | Current order state and tracking fields when available |
Check fit before writing the integration
IRIS accepts PDFs up to 26 MiB. Letter PDFs must use US Letter pages; the current limit is 60 single-sided or 120 double-sided pages. Certified letters are limited to six sheets. The upload link lasts ten minutes, so request it when you are ready to transfer the file.
This API does not provide mailing lists, campaigns, batch personalization, scheduling, EDDM, Marketing Mail, or international delivery. If your requirement is a campaign sent to thousands of recipients, choose a workflow designed for that requirement. For IRIS, keep each mailing tied to an individual reviewed business purpose.
Choose one measurable first workflow
Use a simple success criterion: a colleague can review an existing PDF, see the exact quote, approve it once, and find the resulting order later. Measure preparation time, corrections caught before submission, and exceptions requiring follow-up. Those measurements tell you whether the integration helps your team; a higher mailing count alone does not.
Before live use, test invalid PDFs, missing address fields, insufficient credits, and a lost response using local fixtures or mocked HTTP responses. IRIS developer keys are credentials for credited mailings; do not assume a test_ prefix or a sandbox mode exists. The linked quickstart separates preparation from the command that creates a paid mailing.
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.