Inkly API guide

1. Create and check your API key

Sign in to Integrations in your dashboard. Select Create API key, name your key, and select Create key. Copy the key when it appears; it is shown only once. Keep it on your server, out of browser code and public repositories.

Replace YOUR_API_KEY with the complete key, including its inkly_sk_ prefix. All endpoints use the same authorization header. Check your connection without creating an order:

curl "https://swuhcvokawzzttaambde.supabase.co/functions/v1/inkly-api/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful GET /me returns name, email, balance_cents, and the formatted balance. Add credits in the dashboard's Credits section before sending.

2. Choose a card and handwriting style

Fetch the available options with GET /catalog:

curl "https://swuhcvokawzzttaambde.supabase.co/functions/v1/inkly-api/catalog" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response contains designs with id, name, and desc, plus styles with id, name, and tone. Use the IDs in your send request. Logo cards are not available through the API.

3. Send one card

Save this payload as card.json. Replace each uppercase value with your chosen catalog IDs, message, and recipient details.

{
  "card_design": "YOUR_CARD_DESIGN_ID",
  "handwriting_style": "YOUR_HANDWRITING_STYLE_ID",
  "message": "YOUR_CARD_MESSAGE",
  "recipient": {
    "first_name": "RECIPIENT_FIRST_NAME",
    "last_name": "RECIPIENT_LAST_NAME",
    "address1": "RECIPIENT_STREET_ADDRESS",
    "city": "RECIPIENT_CITY",
    "state": "TWO_LETTER_STATE_CODE",
    "zip": "RECIPIENT_ZIP_CODE"
  }
}

Sending this request places an order and charges your credits. Use a unique event ID for YOUR_UNIQUE_EVENT_ID, such as the ID of the order or deal that triggered the card.

curl -X POST "https://swuhcvokawzzttaambde.supabase.co/functions/v1/inkly-api/cards" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: YOUR_UNIQUE_EVENT_ID" \
  --data-binary @card.json

Message and address requirements

Keep the message within 500 characters and 16 lines. You can personalize it with {{first_name}}, {{last_name}}, and {{company}}; the finished message must also fit within 500 characters. A blank company becomes “your team.”

All recipient fields shown above are required. Use a two-letter US state code and a five-digit ZIP or ZIP+4. You can also include company and address2 inside recipient.

Schedule a card

Add an optional target_arrival field to the top level of your JSON using YYYY-MM-DD. Choose today or a date up to 365 days ahead. Inkly calculates a mail date five business days before that date. Close dates, or requests without a date, mail as soon as possible. The date schedules mailing; delivery timing depends on USPS.

Read the response

A new order returns 201 Created. A successful idempotent replay returns 200 OK. Both contain these fields:

Follow the order's progress on your dashboard.

4. Make retries safe

Send an X-Idempotency-Key header with every card request. Keep it stable for retries of the same event and use a new value for each new card. The value can be up to 255 characters.

When a valid request repeats the same idempotency key with the same API key, Inkly returns the original order with replayed: true and costCents: 0. It does not create or charge for a second card. Reusing a key does not update the original card. Without an idempotency key, a retry can create another order.

Handle errors

Error responses include an error message. Check both the HTTP status and that message before deciding what to retry.