shoot-email AGENTS.md

Shoot Email CLI Planning Notes

Product Direction

Build a terminal-first email client/service that lets users send text emails and check received text emails from the command line. Start with a CLI because it is easy to build, inspect, and debug. Later, wrap the same service layer in an MCP server and use it as the backend for a ChatGPT app.

Recommended Architecture

CLI
  -> local API/service
    -> local database
    -> Cloudflare Email Sending API

Cloudflare Email Routing
  -> Email Worker email() handler
    -> parse inbound email
    -> POST normalized JSON to backend webhook
    -> validate/store message
    -> CLI reads messages from database

The CLI should be the user interface, but it should not be the whole system. Receiving mail requires Cloudflare Email Routing plus a Worker email handler. The Worker parses inbound mail and posts normalized JSON to the backend webhook.

Cloudflare Fit

Cloudflare Email Service is the preferred provider because it supports:

• Receiving inbound mail through Email Routing.
• Running custom inbound logic through an Email Worker.
• Sending outbound mail through Email Sending.
• Keeping DNS, inbound routing, outbound sending, and edge logic on one platform.

For development, use wrangler dev to test Email Routing behavior locally. When a deployed Worker needs to reach a local backend, expose the local webhook with a tunnel such as cloudflared or ngrok until the service is moved to a small cloud host.

Hosting Decision

Host the durable HTTP backend on Cloudflare Workers Paid and use Neon Postgres with pgvector as the managed database. Connect the Worker to Neon through a Hyperdrive binding with query caching disabled initially. Worker requests use a request-scoped pg.Client; local CLI, migration, and integration-test paths continue using pooled Docker Postgres.

Use transaction-scoped lock rows with SELECT ... FOR UPDATE for outbound quota coordination. Do not use PostgreSQL advisory locks through Hyperdrive; they are not supported.