Penpalsapp PenPals API
★ Only Publicly Available OpenAPI DocumentE CommerceOrder Managementbearer45 EndpointsREST
For 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.
Use for: I need to create a handwritten letter order, List all available fonts for letter templates, I want to add items to the cart for bulk mailing, Calculate the total cost for an order before submitting
Not supported: Does not handle digital messaging, email delivery, or SMS — use for physical handwritten mail and postcard orders only.
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.
Install Jentic One Beta
Connect the PenPals API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the PenPals API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with PenPals API.
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
Patterns agents use PenPals API for, with concrete tasks.
★ 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.
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.
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.
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.
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
45 endpoints — jentic publishes the only available openapi specification for penpals api, keeping it validated and agent-ready.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
PenPals Bearer tokens (JWT) are managed by Jentic's credential vault. Token refresh via POST /api/v1/auth/refresh is handled automatically so agents operate without managing JWT lifecycle.
Intent-based discovery
Agents search by intent (e.g., 'send a handwritten letter') and Jentic returns matching PenPals operations including the natural language concierge endpoint, enabling immediate order creation.
Time to first call
Direct PenPals integration: 2-3 days for OAuth flow, cart management logic, and order processing. Through Jentic: under 1 hour — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using PenPals API through Jentic.
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 at https://app.jentic.com/sign-up.
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.
GET STARTED