kindle-send

Send PDFs and checklists to Kindle Scribe via Gmail API. Generates print-ready PDFs with cover pages, multi-column layouts, and checkbox formatting optimized for Kindle Scribe pen annotation.

Features

• Checklist mode — convert structured text files into checkbox PDFs
• Cover page — auto-generated image cover that shows as Kindle library thumbnail
• Multi-column layout — 1, 2, or 3 column support for compact checklists
• HTML/PDF passthrough — send any HTML or existing PDF to Kindle
• Smart naming — filename becomes the Kindle library title, auto-includes date
• PDF metadata — title, author, description embedded in PDF

Setup

1. Gmail API credentials

1. Go to Google Cloud Console
2. Create a project and enable the Gmail API
3. Create OAuth 2.0 credentials (Desktop application)
4. Download the JSON file and save as google_credentials.json in the project root

2. Kindle email address

1. Go to Amazon — Manage Your Content and Devices
2. Find your Kindle's Send-to-Kindle email address (e.g. your_kindle@kindle.com)
3. Add your Gmail address to the Approved Personal Document E-mail List

3. Configuration

cp config.example.json config.json

Edit config.json with your emails:

{
  "kindle": {
    "to_email": "your_kindle_address@kindle.com",
    "from_email": "your_gmail@gmail.com"
  }
}

4. Install dependencies

pip install -r requirements.txt

WeasyPrint requires system dependencies. On macOS:

brew install pango

Usage

Send a checklist

# Simple checklist
./kindle_send.py --checklist shopping.txt

# With cover page, 3 columns, custom title
./kindle_send.py --checklist nature_zones.txt \
  --columns 3 \
  --title "Nature Zones" \
  --description "Flora and Fauna" \
  --author "Geography"

# Generate PDF only (no send)
./kindle_send.py --checklist items.txt --no-send

Send HTML or PDF

./kindle_send.py --html document.html
./kindle_send.py --pdf report.pdf
./kindle_send.py --pdf report.pdf --subject "Weekly Report"

Options

Flag	Description
--checklist FILE	Text file with checklist items
--html FILE	HTML file to convert to PDF
--pdf FILE	Send existing PDF
--title TEXT	Document title (default: filename)
--author TEXT	Author field (default: current date/time)
--description TEXT	Subtitle on cover page
--columns {1,2,3}	Column layout for checklists (default: 1)
--subject TEXT	Email subject (default: filename)
--no-cover	Skip cover page generation
--no-send	Generate PDF only, don't email to Kindle
--output PATH	Custom output path for generated PDF

Checklist format

## Section Header
item1, item2, item3
- single item
* another item

## Another Section
more, items, here

• ## lines become section headers
• Comma-separated items on a line become individual checkboxes
• Lines starting with - or * are single items
• Empty lines are ignored

Example

See examples/nature_zones.txt for a complete example with 10 biome zones.

How it works

1. Parses checklist text into structured sections
2. Generates a cover page image (Pillow) — becomes Kindle library thumbnail
3. Renders HTML with checkboxes to PDF (WeasyPrint)
4. Sends PDF to Kindle via Gmail API
5. Kindle filename = library display title (includes date)
6. Author field shows in Kindle document details

Kindle Scribe tips

• The [ ] checkboxes are designed for pen annotation on Kindle Scribe
• Cover page renders as the library thumbnail for easy identification
• Use --columns 3 for long lists to save pages
• Author field in Kindle details is limited to ~35 characters

License

MIT