canonical: https://jentic.com/apis/handwrytten.com/handwrytten

# Handwrytten API

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.

## For AI agents

Send physical handwritten greeting cards through the mail by selecting a card, font, recipient address, and optional gift card via REST.

## Scope

Does not handle email, SMS, or push delivery - use for printing and mailing physical handwritten cards only.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Cards** — Catalogue browsing, custom card creation, and logo upload
- **Fonts** — Available handwriting styles for card writing
- **Orders** — Single-step order placement
- **Profile** — Recipient address book and return address
- **Gift Cards** — Attachable gift card denominations
- **Auth** — Account registration, login, logout, password reset

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **SendGrid** — Transactional email delivery for digital outreach when a physical card is unnecessary.
- **Twilio** — SMS and voice messaging for instant outreach instead of physical mail.
- **Stripe** — Stripe handles upstream payment events that can trigger thank-you cards via Handwrytten.

## FAQ

### 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.