Send reviewed mail from software or an AI agent.

IRIS provides account-bound API keys, private PDF uploads, prepaid mailing credits, idempotent letter and postcard orders, status, and a Streamable HTTP MCP endpoint.

Download OpenAPI 3.1 JSON

One mailing workflow

  1. Create a scoped irk_ API key in the dashboard.
  2. Buy mailing credits through Stripe.
  3. Create a presigned upload URL for each PDF.
  4. PUT the exact PDF bytes to that URL with every returned uploadHeaders value.
  5. Register each upload and save the immutable document ID.
  6. Quote the mailing and have a person review its document, addresses, price, authority, and intent.
  7. Create one mailing with a unique Idempotency-Key.
  8. Read the mailing status through REST or MCP.

REST API

Send the API key only from trusted server-side software. All amounts are integer US cents. API responses use data for results and error.code plus error.message for failures.

curl https://api.irispostalforms.com/v1/account \
  -H "Authorization: Bearer irk_REDACTED"

curl -X POST https://api.irispostalforms.com/v1/uploads/presign \
  -H "Authorization: Bearer irk_REDACTED" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"letter.pdf","sizeBytes":48211,"kind":"letter"}'

Use letter, postcard_4x6, or postcard_6x9 as the document kind. Postcards require separate one-page front and back PDFs with the exact bleed dimensions.

MethodPathScopePurpose
GET/v1/accountaccount:readBalance
POST/v1/uploads/presigndocuments:writePrivate PUT URL
POST/v1/documentsdocuments:writeValidate and register PDF
POST/v1/mailings/quotemailings:readExact price
POST/v1/mailingsmailings:writeSubmit one mailing
GET/v1/mailings/:idmailings:readStatus and tracking

The account receives 60 API requests per minute. Document uploads remain subject to the 26 MB PDF limit and product page limits.

Quote, review, then submit

curl -X POST https://api.irispostalforms.com/v1/mailings/quote \
  -H "Authorization: Bearer irk_REDACTED" \
  -H "Content-Type: application/json" \
  -d '{
    "product":"letter",
    "primaryDocumentId":"DOCUMENT_UUID",
    "sender":{"recipient":"Ada Sender","primaryLine":"1 Main St","city":"Boston","state":"MA","zipCode":"02108"},
    "recipient":{"recipient":"Grace Recipient","primaryLine":"2 State St","city":"Boston","state":"MA","zipCode":"02109"},
    "options":{"color":false,"double_sided":true,"certified":false,"certified_return_receipt":false}
  }'

curl -X POST https://api.irispostalforms.com/v1/mailings \
  -H "Authorization: Bearer irk_REDACTED" \
  -H "Idempotency-Key: order_018f_reviewed" \
  -H "Content-Type: application/json" \
  --data-binary @reviewed-mailing.json

For a postcard, use product: "postcard", provide front primaryDocumentId and back secondaryDocumentId, and select the matching 4x6 or 6x9 size. See OpenAPI JSON for the complete option schema.

MCP for AI applications

Connect an MCP client to https://api.irispostalforms.com/mcp with the API key in the Authorization header. The server exposes account balance, private upload creation, document registration, quote, submission, and status tools.

{
  "mcpServers": {
    "iris-postal-forms": {
      "url": "https://api.irispostalforms.com/mcp",
      "headers": {
        "Authorization": "Bearer irk_REDACTED"
      }
    }
  }
}

Keep a person in the mailing decision

An AI agent may prepare a payload, calculate a price, and submit a reviewed order. The person or organization operating the agent remains responsible for the document, image rights, message, addresses, recipient authority, legal requirements, available credits, and decision to send.

Use a new idempotency key for each intended mailing. Reusing the same key with the same payload returns the original order. Reusing it with different details returns a conflict.