Handwrytten API
Community OpenAPI document · agent-readyCommunicationsEmail DeliveryapiKey30 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Send physical handwritten greeting cards through the mail by selecting a card, font, recipient address, and optional gift card via REST.
Use for: Send a handwritten thank-you card to a customer, Upload our company logo as a custom card cover, List all available handwriting fonts in the Handwrytten catalogue, Add a new recipient to my Handwrytten address book
Not supported: Does not handle email, SMS, or push delivery - use for printing and mailing physical handwritten cards only.
Handwrytten is a service that prints and mails physical greeting cards written by robots in a chosen handwriting style. The API exposes 30 endpoints for browsing the card catalogue, uploading custom card artwork and logos, managing recipient address books, placing single-step orders, and adding gift cards to a send. Authentication uses a session UID returned from /auth/authorization, and orders draw from a configured payment method or monthly invoice. Card delivery is physical mail, not email or SMS.
Install Jentic One Beta
Connect the Handwrytten API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Handwrytten 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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhandwrytten.com%2Fhandwrytten" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhandwrytten.com%2Fhandwrytten" | 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 Handwrytten API.
Browse the Handwrytten card catalogue and pull a specific card's full details
Upload a custom card design or logo for reuse across orders
List available handwriting fonts including those compatible with the customizer
Add, list, and delete recipient addresses in the user's account
Place a single-step order that selects card, message, font, and recipient in one call
Attach a gift card to a Handwrytten order at checkout
Use Cases
Patterns agents use Handwrytten API for, with concrete tasks.
★ Customer Win-Back Cards
Trigger a handwritten thank-you or win-back card whenever a high-value customer hits a milestone in a CRM. The Handwrytten API places a single-step order via /orders/singleStepOrder with the card, font, message, and recipient address, and returns an order confirmation. Cards typically print and ship within 1-2 business days from the API call.
When a Salesforce opportunity closes-won above $10k, call POST /orders/singleStepOrder with a thank-you card, the rep's font, and the customer's mailing address.
Branded Card Templates
Upload a company logo or custom card front via /cards/uploadCustomLogo and /cards/createCustomCard so future orders use a branded design without re-uploading. The API stores the custom card and returns a card ID that can be referenced like any catalogue card. Useful for marketing teams that want a consistent look across all handwritten outreach.
Upload a PNG logo via POST /cards/uploadCustomLogo and then POST /cards/createCustomCard to register the branded design as card template 'company-thanks-2026'.
Gift Card with Greeting
Bundle a handwritten card with an attached gift card for referral rewards or employee recognition. Use /giftCards/view to confirm available denominations, then place the order through /orders/singleStepOrder with the gift card payload included. Handwrytten handles printing, gift card attachment, and physical delivery in a single API call.
Send a handwritten congratulations card with a $25 gift card to a new hire's home address using POST /orders/singleStepOrder.
AI Agent Mail Automation
Let an AI agent send physical thank-you cards on behalf of a sales rep when a deal closes. Through Jentic the agent searches for 'send a handwritten card', loads the /orders/singleStepOrder schema, and executes with the recipient and message. The session UID is rotated by Jentic so the agent never holds long-lived credentials.
When asked 'send Amy a thank-you card for the demo', call POST /orders/singleStepOrder with cardId, font, message, and Amy's address from the recipient list.
Key Endpoints
30 endpoints — handwrytten is a service that prints and mails physical greeting cards written by robots in a chosen handwriting style.
METHOD
PATH
DESCRIPTION
POST
/auth/authorization
Log in and obtain a session UID
POST
/orders/singleStepOrder
Place a card order in a single call
GET
/cards/list
List available cards
POST
/cards/createCustomCard
Create a custom card design
POST
/cards/uploadCustomLogo
Upload a logo or cover image
GET
/fonts/list
List available handwriting fonts
POST
/profile/profileAddRecipient
Add a recipient address
POST
/profile/recipientsList
List recipients in the user's account
POST
/auth/authorization
Log in and obtain a session UID
POST
/orders/singleStepOrder
Place a card order in a single call
GET
/cards/list
List available cards
POST
/cards/createCustomCard
Create a custom card design
POST
/cards/uploadCustomLogo
Upload a logo or cover image
GET
/fonts/list
List available handwriting fonts
POST
/profile/profileAddRecipient
Add a recipient address
POST
/profile/recipientsList
List recipients in the user's account
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Handwrytten API by hand means exchanging your account email and password at /auth/authorization, carrying the returned session for each call, and building every card, order, and recipient request yourself. Through Jentic you install once, import the Handwrytten API from the API Directory, store the account credentials once, and your agent calls it.
Permission scoping
The Handwrytten API carries its targets, such as the recipient and card, in the request body, so scope your agent to the operations it needs, such as placing a single-step order or listing cards. You choose what it may call, so creating custom cards or uploading logos are not included unless you add them.
Credential isolation
Your Handwrytten account email and password are stored once, encrypted, by your own Jentic One instance, which performs the authorization exchange and holds the session only for the call. They never enter the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'send a handwritten thank you card', and Jentic returns the POST /orders/singleStepOrder operation with its input schema so the agent calls the right endpoint without reading the SwaggerHub docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
Complementary
Stripe
Stripe handles upstream payment events that can trigger thank-you cards via Handwrytten.
Pair Stripe (purchase event) with Handwrytten (post-purchase card) when a thank-you card is part of post-payment customer experience.
FAQs
Specific to using Handwrytten API through Jentic.
What authentication does the Handwrytten API use?
Handwrytten uses session-based auth. Call POST /auth/authorization with email and password to receive a session UID, then include the UID with subsequent requests; POST /auth/logout invalidates the session. Through Jentic the credentials live in the encrypted vault and the session UID is rotated automatically.
Can I send a handwritten card in a single API call with Handwrytten?
Yes. POST /orders/singleStepOrder accepts the cardId, font, message, recipient address, and optional gift card in one request and returns an order confirmation. This avoids chaining the cart, address, and checkout endpoints separately.
What are the rate limits for the Handwrytten API?
Handwrytten does not publish a documented per-second rate limit. Their support team recommends contacting contact@handwrytten.com for sandbox accounts or to request bulk send throughput. Build clients to back off on HTTP 429 if encountered.
How do I send a thank-you card through Jentic?
Search Jentic for 'send a handwritten thank you card', load the schema for POST /orders/singleStepOrder, and execute with cardId, font, message, and recipient. Run pip install jentic and use the async client.search, client.load, and client.execute pattern.
Does Handwrytten support email or SMS delivery?
No. Handwrytten prints physical cards with a robotic handwriting machine and mails them via standard postal services. There is no email or SMS channel. For digital delivery, pair Handwrytten with a separate email or SMS API.
Can I attach a gift card to a Handwrytten order?
Yes. Call /giftCards/view to confirm available denominations and brands, then include the gift card payload in the POST /orders/singleStepOrder request body. The gift card is enclosed inside the printed card and mailed together.
Can I limit what my agent is allowed to do with the Handwrytten API?
Yes. Because Jentic One is self-hosted by you, your own rules decide which Handwrytten operations and credentials the agent may use, so you can allow it to place a single-step order via POST /orders/singleStepOrder or list cards via GET /cards/list while excluding everything else. Since the API carries its targets, such as the recipient and card, in the request body, you scope the agent to only the operations it needs. Sensitive actions like creating custom cards or uploading logos are not available to the agent unless you explicitly add them.
GET STARTED