canonical: https://jentic.com/apis/intelliprint.net/intelliprint

# Intelliprint API Reference

The Intelliprint API prints and posts physical letters and postcards from code. A print job can be built from text or HTML content, a template, or an uploaded file, and sent to a list of recipients or to a saved mailing list, with control over printing options, postage service, envelope or postcard size, and the mailing date. It also splits a single file of pre-addressed letters into separate mailings, applies reusable letterhead backgrounds, and runs jobs in testmode so nothing is charged or sent until you confirm.

## For AI agents

Create, confirm, track, and cancel Intelliprint letter and postcard print jobs, and manage the mailing lists, recipients, and backgrounds they use.

## Scope

Does not handle email, SMS, address verification as a standalone service, or parcel shipping. Use for printing and posting letters and postcards and managing their mailing lists only.

## Capabilities

- Create a letter or postcard print job from content, a template, or an uploaded file, and send it to recipients or a mailing_list
- Run a job in testmode to preview it without charge, then set confirmed to submit it for printing
- Choose a postage service such as uk_first_class, uk_special_delivery, tracked_24, or international, plus envelope size and mail_date
- Split one uploaded file of pre-addressed letters into separate mailings by phrase, by page count, or by mailing list
- Keep reusable mailing lists and update individual recipients' addresses and template variables
- Upload letterhead backgrounds once and apply them to any print job
- List print jobs filtered by type, reference, confirmed, or letters.status, and cancel a job that has not yet printed

## Use cases

### Agent-sent postal letters through Jentic

An AI agent connected through Jentic posts a physical letter when a workflow calls for one, such as a final payment reminder or a contract that must arrive on paper. It creates the print job with HTML content and the recipient's address in testmode, checks the result, then confirms the job for printing. The API key stays in your own Jentic One instance, never in the agent's context.

Example prompt: Call POST /prints with type 'letter', content set to the reminder text for invoice INV-2041, one recipient address, and testmode true, then POST `/prints/{id}` with confirmed true once the preview is correct

### Postcard campaigns to a mailing list

Marketing teams send a postcard to a saved list. Create the mailing list with a name and recipients, each with an address and optional variables for personalisation, then create a print job of type postcard with the mailing_list id. Postcards can be sent with the uk_first_class or uk_second_class postage services, in sizes such as postcard_a6 or postcard_a5.

Example prompt: Call POST /mailing_lists with name 'Black Friday Leads' and the recipients, then POST /prints with type 'postcard', the returned mailing_list id, and postage service 'uk_second_class'

### Bulk letters from one pre-addressed file

Billing systems often output one PDF holding many statements, each with its address already printed. Upload it as a single print job and use splitting with the split_on_phrase or split_on_pages method to turn it into separate letters. Intelliprint extracts the addresses from the file, and nudge settings shift the address into the envelope window if needed.

Example prompt: Call POST /prints with type 'letter', the statements file, and splitting method 'split_on_phrase' with the phrase 'Statement date', in testmode true, then review the resulting letters

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/prints` | Create a print job |
| GET | `/prints` | List print jobs |
| GET | `/prints/{id}` | Retrieve a print job |
| POST | `/prints/{id}` | Update or confirm a print job |
| DELETE | `/prints/{id}` | Delete or cancel a print job |
| POST | `/mailing_lists` | Create a mailing list |
| POST | `/mailing_lists/{mailing_list}/recipients` | Add a recipient to a mailing list |
| POST | `/backgrounds` | Upload a background |

## Key resources

- **Print jobs** — Create, list, read, update, confirm, and cancel letter and postcard jobs
- **Mailing lists** — Create, list, read, update, and delete mailing lists
- **Mailing list recipients** — Add, list, read, update, and remove recipients in a mailing list
- **Backgrounds** — Upload, list, read, rename, and delete letterhead backgrounds

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 59 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 83 / 100
  - Developer Experience & Jentic Compatibility: 72 / 100
  - AI-Readiness & Agent Experience: 35 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 73 / 100
- **View full report:** https://jentic.com/apis/intelliprint.net/intelliprint/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Intelliprint by hand means sending its bearer key, building multipart print jobs with postage, printing, and splitting objects, and handling the testmode then confirm sequence. Through Jentic you install once, import Intelliprint from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Intelliprint puts print job, mailing list, and background ids in the URL path (`/mailing_lists/{mailing_list}/recipients`), so a rule can pin your agent to one mailing list and the operations you pick. You choose the operations it may call, so ones like cancelling print jobs or deleting mailing lists are not included unless you add them.
- **Credential handling:** Your Intelliprint API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a physical letter' or 'mail a postcard to a list', and Jentic returns the matching Intelliprint operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stannp API** — Direct mail letters and postcards with campaign tools
- **ClickSend API** — SMS, voice, email, and post letters from one account
- **IndiePitcher API** — Transactional and mailing-list email sending

## FAQ

### Is there an Intelliprint MCP server?

You don't need an MCP server to give your agent Intelliprint. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. The agent finds the print job or mailing list operation it needs on demand, without a server's tool definitions sitting in its context.

### Can I limit what my agent is allowed to do with the Intelliprint API?

Yes. For a tracking agent, write a rule that allows only GET /prints and GET `/prints/{id}.` The agent can list jobs and check each letter's status, but it cannot create, confirm, or cancel anything, and every call it makes is logged. Keep in mind that testmode and confirmed travel in the request body, so a rule that allows POST /prints allows both test and live jobs. To keep a list-maintenance agent on one list, allow the recipient operations under `/mailing_lists/{mailing_list}/recipients` for that list's id only.

### What authentication does the Intelliprint API use?

Per its OpenAPI spec, the Intelliprint API uses HTTP bearer authentication: send your account's API key in the `Authorization` header as `Bearer <key>`. Keys are created in the Intelliprint account dashboard. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected when each call runs.

### Can I test Intelliprint print jobs without paying?

Yes. Set testmode to true when creating a print job: per the spec, test mode jobs are not charged and are not sent. A job is only submitted for printing once confirmed is true, and after that it can no longer be updated.

### What are the rate limits for the Intelliprint API?

The OpenAPI spec does not specify rate limits; check https://intelliprint.net or contact hello@intelliprint.net for current limits.

### Which postage services does the Intelliprint API support?

The postage service field in the spec lists options including uk_second_class, uk_second_class_signed_for, uk_first_class, uk_first_class_signed_for, uk_special_delivery_9am, uk_special_delivery, tracked_24, tracked_48, and international. Postcards can currently only use uk_second_class or uk_first_class.

### How do I send a letter with the Intelliprint API through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import Intelliprint from the API Directory, and store your API key. Your agent searches for 'send a physical letter', gets POST /prints with its input schema, and calls it with type letter, the content, and the recipients, then confirms the job. To run it on your own infrastructure, install Jentic One from its GitHub repo.