Merge pull request #6 from noc0dev/feature/draft

Add email.draft command for safe AI agent email workflows

Author: turian

.gitignore

@@ -12,3 +12,4 @@ wheels/
 # Editor files
 *.swp
 *~
+.aider*

README.md

@@ -5,7 +5,7 @@
 <h1 align="center">fastmail-cli</h1>
 
 <p align="center">
-  <strong>Read-only email access for AI agents via JMAP.</strong>
+  <strong>Read-only email access for AI agents via JMAP, and draft responses.</strong>
 </p>
 
 <p align="center">
@@ -38,7 +38,7 @@ uvx fastmail-cli help
 ## Setup
 
 ```bash
-export FASTMAIL_READONLY_API_TOKEN="fmu1-..."  # from Fastmail Settings → Integrations
+export FASTMAIL_API_TOKEN="fmu1-..."  # from Fastmail Settings → Integrations
 ```
 
 ## Usage
@@ -50,6 +50,37 @@ fastmail-cli email.get --ids '["M123"]'        # get by ID
 fastmail-cli mailbox.query                     # list mailboxes
 ```
 
+### Create Drafts (Safe for AI Agents)
+
+```bash
+# Create a draft - human reviews in Fastmail UI before sending
+fastmail-cli email.draft \
+  --to "recipient@example.com" \
+  --subject "Re: Your question" \
+  --body "Here's the response..."
+
+# Draft with body from file
+fastmail-cli email.draft \
+  --to "user@example.com" \
+  --subject "Report" \
+  --body @report.txt
+```
+
+### Draft Replies to Existing Emails
+
+```bash
+# Reply to an email (auto-threads, auto-sets subject)
+fastmail-cli email.draft-reply \
+  --id "M12345" \
+  --body "Thanks for reaching out..."
+
+# Reply-all to include all original recipients
+fastmail-cli email.draft-reply \
+  --id "M12345" \
+  --body "Replying to everyone..." \
+  --reply-all
+```
+
 All output is JSON with `ok`, `command`, `meta`, and `data`/`error` fields.
 
 ## Required Reading

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "fastmail-cli"
-version = "0.1.1"
-description = "Read-only CLI for agents to access Fastmail via JMAP"
+version = "0.2.0"
+description = "CLI for AI agents to access Fastmail via JMAP - draft responses without sending"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.13"
@@ -30,7 +30,7 @@ Repository = "https://github.com/noc0dev/fastmail-cli"
 Issues = "https://github.com/noc0dev/fastmail-cli/issues"
 
 [project.scripts]
-fastmail-cli = "fastmail_cli:main"
+fastmail-cli = "fastmail_cli.cli:main"
 
 [build-system]
 requires = ["hatchling"]

src/fastmail_cli/cli.py

@@ -6,15 +6,20 @@
 import sys
 
 DEFAULT_HOST = "api.fastmail.com"
-DEFAULT_TOKEN_ENV = "FASTMAIL_READONLY_API_TOKEN"
+DEFAULT_TOKEN_ENV = "FASTMAIL_API_TOKEN"
+LEGACY_TOKEN_ENV = "FASTMAIL_READONLY_API_TOKEN"
 
 
 def main(argv=None) -> int:
     # Set default host if not provided
     os.environ.setdefault("JMAP_HOST", DEFAULT_HOST)
-    # Promote FASTMAIL_READONLY_API_TOKEN to JMAP_API_TOKEN if not already set
-    if "JMAP_API_TOKEN" not in os.environ and DEFAULT_TOKEN_ENV in os.environ:
-        os.environ["JMAP_API_TOKEN"] = os.environ[DEFAULT_TOKEN_ENV]
+    # Promote FASTMAIL_API_TOKEN to JMAP_API_TOKEN if not already set
+    # Fall back to legacy FASTMAIL_READONLY_API_TOKEN for backwards compatibility
+    if "JMAP_API_TOKEN" not in os.environ:
+        if DEFAULT_TOKEN_ENV in os.environ:
+            os.environ["JMAP_API_TOKEN"] = os.environ[DEFAULT_TOKEN_ENV]
+        elif LEGACY_TOKEN_ENV in os.environ:
+            os.environ["JMAP_API_TOKEN"] = os.environ[LEGACY_TOKEN_ENV]
     from .jmapc import main as jmap_main
     return jmap_main(argv)