# InboxToKindle: setup guide for AI agents

InboxToKindle gives a person an inbox address (name@inboxtokindle.com). Newsletters sent there are cleaned, converted to EPUB and delivered to their Kindle or Boox. You can do almost all of the setup for the user through this API. The user only has to: approve you (one click in an email), add one approved sender on Amazon (Kindle only; there is no Amazon API for it), and optionally read back a code from their device.

Base URL: https://substacktokindle.com
All requests and responses are JSON. After step 2, send `Authorization: Bearer <token>` on every call.

## 1. Connect (needs the user's email address)

    POST /api/v1/agent/connect
    {"email": "user@example.com", "agent_name": "Claude"}

Returns `connection_id`, `poll_secret` and `user_code`. Tell the user: "Check your email from InboxToKindle, make sure it shows code XXXX-XXXX, and click Approve." Use the user's real email, never an @inboxtokindle.com address. This works both for new users (the account is created on approval) and existing ones.

## 2. Get your token

    POST /api/v1/agent/token
    {"connection_id": "...", "poll_secret": "..."}

Poll every 5 seconds. `202 {"status": "pending"}` means keep waiting. `200` returns `{"token": "..."}` exactly once; store it. `403 denied` means the user declined. `410 expired` means start again (links last 30 minutes).

## 3. Follow the checklist

    GET /api/v1/setup

Returns `inbox_email`, `next_action` and `steps`. Each step has a `status` (`pending`, `needs_human`, `done`), `who` should act and `instructions`. Repeat: do `next_action`, then call `/api/v1/setup` again until `complete` is true.

### Device: Kindle

Ask the user for their Send-to-Kindle address (ends in @kindle.com; it's NOT their Amazon login) and Amazon country (us, uk, ca, au, de, fr, es, it, jp, in, mx, br, nl).

    POST /api/v1/devices/kindle
    {"kindle_email": "name_abc@kindle.com", "amazon_country": "us", "name": "Kindle"}

The response includes the approved-sender step: the user must open the Amazon link given and add their own InboxToKindle address (the `value_to_add` in that step, the same as `inbox_email`) to their Approved Personal Document E-mail List. Each user's documents are sent from their own address. If you can operate a browser in the user's own Amazon session, you may do this for them with their permission. Then:

    POST /api/v1/devices/{id}/test       -> sends a welcome document with a 6-digit code
    POST /api/v1/devices/{id}/verify     {"code": "123456"}

Ask the user for the code shown on their Kindle. If nothing arrives within 5 minutes, the approved sender is almost always missing or mistyped.

### Device: Boox

    POST /api/v1/devices/boox            {"boox_email": "...", "region": "push"}   ("eur" for Europe accounts)
    POST /api/v1/devices/boox/verify     {"boox_email": "...", "region": "push", "code": "...", "name": "Boox"}

Boox emails the code to the user's Boox account address; ask them for it.

### Subscribe to newsletters

Subscribe using the user's `inbox_email` (for Substack, the subscribe box on the publication's page). Many platforms send a confirmation email first:

    GET  /api/v1/confirmations
    POST /api/v1/confirmations/{id}/confirm   -> we click the confirmation link server-side

Or turn on automatic confirmation:

    PATCH /api/v1/preferences   {"auto_confirm_subscriptions": true}

Only newsletter subscription confirmations are ever exposed or clicked. Sign-in codes, magic links, password resets and other account-security emails are never available to agents; they go to the user's real inbox. If the user wants an existing Substack subscription moved over, they change their email in Substack's account settings themselves.

## Other endpoints

    GET   /api/v1/inbox                 PATCH {"username": "jane"} -> jane@inboxtokindle.com
    GET   /api/v1/devices               DELETE /api/v1/devices/{id}
    GET   /api/v1/preferences           PATCH any of: delivery_mode (instant|daily|weekly),
                                        delivery_time ("HH:MM"), delivery_weekday (0=Mon..6),
                                        timezone (IANA, e.g. "America/Mexico_City"),
                                        filter_substack_notifications, auto_confirm_subscriptions
    GET   /api/v1/newsletters           25 most recent deliveries and their status
    POST  /api/v1/billing/checkout      {"plan": "monthly"|"annual"} -> checkout_url for the user to pay
    POST  /api/articles/                {"html": "...", "title": "...", "url": "..."} send a web article

## Plans

Free: 3 deliveries per month, no card. Pro: 10 USD/month or 100 USD/year, unlimited. Only the user can pay; give them the `checkout_url`. Don't promise a free trial.

## Errors

Errors look like `{"error": "code", "message": "human-readable explanation"}`. 401 means a missing or revoked token, 429 means slow down, 4xx messages are safe to relay to the user.