File Formats

Directory layout

mail/
  conversations/          # One file per thread, all sources merged
    project-update.md     # Immutable slug filename
    lunch-plans.md        # mtime = last message date
  contacts/               # Per-contact context for drafting
    alex/
      AGENTS.md           # Relationship, tone, topics, notes
      CLAUDE.md -> AGENTS.md
  drafts/                 # Outgoing messages
  mailboxes/              # Named mailboxes
    {name}/
      conversations/
      drafts/
      contacts/
      AGENTS.md
      CLAUDE.md -> AGENTS.md
      README.md
      voice.md
  manifest.toml           # Thread index (generated by sync)
  .sync-state.json        # IMAP sync state
  .corky.toml             # Configuration
  voice.md                # Writing style guidelines

Conversation markdown

Each synced thread is a single Markdown file in conversations/:

# [Subject]

**Labels**: label1, label2
**Accounts**: account1, account2
**Thread ID**: thread key
**Last updated**: RFC 2822 date

---

## Sender Name <email@example.com> — Mon, 01 Jan 2024 12:00:00 +0000

Body text

---

## Reply Sender — Tue, 02 Jan 2024 09:00:00 +0000

Reply body

No subdirectories for accounts or labels. A conversation with the same person may arrive via Gmail, Protonmail, or both — it merges into one file. Source metadata is tracked inside each file.

Immutable filenames. Each thread gets a [slug].md name derived from the subject on first write. The filename never changes. Thread identity is tracked by **Thread ID** metadata.

File mtime is set to the last message date. ls -t sorts by thread activity.

Draft markdown

Drafts live in mail/drafts/ (private) or mail/mailboxes/{name}/drafts/ (collaborator). Filename convention: [YYYY-MM-DD]-[slug].md.

# [Subject]

**To**: recipient@example.com
**CC**: (optional)
**Status**: draft
**Author**: brian
**Account**: (optional — account name from .corky.toml)
**From**: (optional — email address)
**In-Reply-To**: (optional — message ID)

---

Draft body goes here.

Status values: draft → review → approved → sent

manifest.toml

Generated after each sync. Indexes threads by subject, labels, accounts, contacts, and last-updated date.

[threads.project-update]
subject = "Project Update"
thread_id = "project update"
labels = ["correspondence"]
accounts = ["personal"]
last_updated = "Mon, 01 Jan 2024 12:00:00 +0000"
contacts = ["alex"]

.sync-state.json

Tracks IMAP UIDs per-account for incremental sync.

{
  "accounts": {
    "personal": {
      "labels": {
        "correspondence": {
          "uidvalidity": 12345,
          "last_uid": 67890
        }
      }
    }
  }
}