canonical: https://jentic.com/apis/penpalsapp.com/penpals

# Penpalsapp PenPals API

Jentic publishes the only available OpenAPI specification for PenPals API, keeping it validated and agent-ready. PenPals API powers a handwritten letter and postcard marketplace with 45 endpoints covering addresses, cart management, orders, products, templates, and authentication. It supports creating orders from natural language via a concierge endpoint, managing handwritten letter templates with custom fonts and ink colors, and processing orders for physical mail delivery.

## For AI agents

Create and manage handwritten letter orders including addresses, cart items, templates with custom fonts and ink colors, and order processing. Supports natural language order creation via a concierge endpoint.

## Scope

Does not handle digital messaging, email delivery, or SMS - use for physical handwritten mail and postcard orders only.

## Capabilities

- Create handwritten letter orders from natural language descriptions via a concierge endpoint
- Manage recipient addresses individually or in bulk for mail campaigns
- Design letter templates with custom font and ink color selections
- Process cart items through to completed orders with cost calculation
- Browse product categories and extras for handwritten mail customization
- Manage return addresses for consistent sender branding

## Use cases

### Automated Handwritten Mail Campaigns

Send personalized handwritten letters at scale by managing addresses in bulk and creating orders programmatically. The API supports bulk address creation (POST `/api/v1/addresses/bulk`), template management with custom fonts and ink colors, and order processing. Agents can orchestrate campaigns that feel personal while operating at marketing scale.

Example prompt: Create 5 addresses via POST `/api/v1/addresses/bulk`, select a template with a cursive font, add items to cart via POST `/api/v1/cart`, then create an order via POST `/api/v1/orders/create`

### Natural Language Order Creation

Create handwritten letter orders from plain-text descriptions using the concierge endpoint. POST `/api/v1/orders/concierge` accepts natural language input and produces a structured order, reducing the steps needed to go from idea to physical mail. This enables chatbot and agent-driven order flows without explicit template or product selection.

Example prompt: Submit a natural language description to POST `/api/v1/orders/concierge`: 'Send a thank-you letter to John at 123 Main St in blue ink with a friendly tone'

### Template Library Management

Build and manage a library of reusable letter templates with specific fonts, ink colors, and content layouts. The API provides GET `/api/v1/templates/fonts` for available fonts, GET `/api/v1/templates/ink-colors` for color options, and full CRUD on templates. Agents can maintain branded template collections for different customer communication scenarios.

Example prompt: Retrieve available fonts via GET `/api/v1/templates/fonts`, select a script font, then create a template via POST `/api/v1/templates` with the chosen font and blue ink color

### AI Agent Mail Operations via Jentic

AI agents discover and execute PenPals operations through Jentic to send handwritten mail without building a custom integration. Agents search for mail capabilities by intent, receive typed operation schemas, and create orders or manage templates through Jentic's unified interface. OAuth token handling and endpoint discovery are managed automatically.

Example prompt: Search Jentic for 'send a handwritten letter', load the POST `/api/v1/orders/concierge` schema, and execute with a natural language order description

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/orders/concierge` | Create order from natural language |
| POST | `/api/v1/orders/create` | Create a new order |
| POST | `/api/v1/orders/calculate` | Calculate order cost |
| POST | `/api/v1/addresses/bulk` | Create multiple addresses |
| GET | `/api/v1/products` | List all products |
| POST | `/api/v1/templates` | Create a letter template |
| GET | `/api/v1/templates/fonts` | List available fonts |
| POST | `/api/v1/cart` | Add item to cart |

## Key resources

- **Addresses** — Manage recipient addresses individually and in bulk
- **Cart** — Add, update, and remove items from the shopping cart
- **Orders** — Create orders, calculate costs, and use natural language concierge
- **Products** — Browse products, categories, and extras
- **Templates** — Create and manage letter templates with fonts and ink colors
- **Return Addresses** — Manage sender return addresses

## 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:** 49 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 76 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 22 / 100
  - Agent Usability: 94 / 100
  - Security: 75 / 100
  - AI Discoverability: 80 / 100
- **View full report:** https://jentic.com/apis/penpalsapp.com/penpals/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 PenPals by hand means managing its JWT bearer tokens and their refresh lifecycle and assembling order, address, and template payloads for handwritten mail yourself. Through Jentic you install once, import the PenPals API from the API Directory, store the token once, and your agent calls it while refresh is handled for you.
- **Permission scoping:** PenPals takes its order details in the request body across endpoints like `/api/v1/orders/create` and `/api/v1/orders/concierge`, so scoping is operations-only: limit the agent to the operations it needs, such as calculating and creating an order, and leave bulk address upload or template creation out of the allowed set unless you add them.
- **Credential handling:** Your PenPals bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time, with refresh handled automatically. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a handwritten letter', and Jentic returns the matching PenPals operation, including the natural-language concierge endpoint, with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stannp API** — Stannp provides direct mail printing and delivery for postcards, letters, and flyers without the handwritten style.
- **Handwrytten API** — Handwrytten offers robot-written handwritten notes and cards with customizable handwriting styles.
- **Click2Mail API** — Click2Mail handles printed business mail, statements, and bulk postal campaigns that complement PenPals personal letters.

## FAQ

### Why is there no official OpenAPI spec for PenPals API?

PenPals does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call PenPals API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the PenPals API use?

The PenPals API uses Bearer token authentication with JWT format. Obtain a token via POST `/api/v1/auth/token` using OAuth 2.0 credentials. Through Jentic, token acquisition and refresh are handled automatically so agents do not manage the auth flow directly.

### Can I create orders from natural language descriptions?

Yes. POST `/api/v1/orders/concierge` accepts a natural language description and produces a structured order. This endpoint handles product selection, address parsing, and template matching from plain-text input, enabling conversational order creation.

### How do I manage addresses in bulk through Jentic?

Search Jentic for 'create multiple recipient addresses' to discover the POST `/api/v1/addresses/bulk` endpoint. Load the operation schema and execute with an array of address objects. The API also supports PATCH `/api/v1/addresses/bulk` for bulk updates and DELETE `/api/v1/addresses/bulk` for removal.

### What fonts and ink colors are available for templates?

GET `/api/v1/templates/fonts` returns all available handwriting fonts, and GET `/api/v1/templates/ink-colors` returns the available ink color options. Use these values when creating templates via POST `/api/v1/templates` to specify the visual style of letters.

### Can I calculate order costs before submitting?

Yes. POST `/api/v1/orders/calculate` accepts the same payload as order creation and returns the total cost breakdown without actually creating the order. This enables cost preview and approval workflows before committing to physical mail production.

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

Yes. Because you run Jentic One yourself, your own rules decide which PenPals operations and credentials the agent may use, so you allow only the endpoints it needs. For example, you can permit calculating and creating an order (POST `/api/v1/orders/calculate` and POST `/api/v1/orders/create` or the concierge endpoint) while leaving bulk address upload (POST `/api/v1/addresses/bulk`) and template creation (POST `/api/v1/templates`) out of the allowed set. Scoping is operations-based, since PenPals passes order details in the request body, and the stored bearer token is injected only when a permitted operation runs.