sophiamyang/media-content-skills/kindle-delivery

Sending documents to a Kindle

Amazon accepts personal documents by email. The mechanics are simple; the failure modes are quiet, which is what makes this worth writing down.

Established August 2026.

The delivery path

Send an email with the document attached to the device's @kindle.com address. Two requirements Amazon enforces, both of which fail silently from the sender's side:

• The sending address must be on Amazon's approved personal document email list (Amazon account → Manage Your Content and Devices → Preferences → Personal Document Settings). An unapproved sender is dropped without a bounce. If a send "succeeds" but nothing arrives, check this first.
• EPUB is accepted for modern Kindles. Converting Markdown to EPUB with pandoc works well.

Gmail API over SMTP

Prefer the Gmail API to SMTP: it uses OAuth rather than an app password, which is both safer and less likely to be blocked.

Setup is a one-time interactive flow — download an OAuth Desktop client JSON from Google Cloud, run a local consent flow, and save the resulting token. The token then works unattended.

For servers and containers, ship the credential and token JSON as base64 environment variables and materialise them at startup:

data = base64.b64decode(os.environ["GMAIL_TOKEN_JSON_B64"]).decode()
json.loads(data)                      # validate before writing
Path("config/private/gmail_token.json").write_text(data)

Validate the JSON before writing rather than discovering the corruption at send time. A common real-world cause is a value pasted with curly quotes wrapped around it, which makes base64 decoding fail with an opaque error — strip “”‘’"' from both ends before decoding.

Note that Google refreshes the access token in that file as it is used. In an ephemeral container those updates are discarded, which is fine: the refresh token inside remains valid. It does mean an expired or revoked token must be re-issued locally and the environment variable updated.

Runnable reference

send_to_kindle.py in this folder implements the above, standalone — no project imports.

python send_to_kindle.py book.epub --setup    # one-time OAuth consent
python send_to_kindle.py book.epub

Needs google-api-python-client, google-auth-oauthlib, google-auth-httplib2. Reads credentials from files or from base64 environment variables, stripping the curly quotes that a pasted value often carries.

Quiet failure modes to guard against

• Missing pandoc. A build that converts Markdown to EPUB will often fall back to sending Markdown rather than erroring. The send "succeeds" and the reader gets the wrong format. Check the converter exists and fail loudly if it does not.
• Sending a stale file. Scripts that pick "the newest file in the output directory" will happily send an abandoned build. If a specific artifact is the deliverable, name it explicitly, or refresh the output path before sending.
• Unapproved sender, as above — no bounce, no error, no delivery.

Do not resend blindly

Record successful sends (filename or content hash, plus timestamp) and skip anything already delivered unless the caller explicitly forces it. Re-sending a large book people have already received is a real annoyance, and re-runs are common when a pipeline is retried.