outreach-desk 2.0.0__tar.gz

outreach_desk-2.0.0/.dockerignore

@@ -0,0 +1,9 @@
+.git
+.venv
+**/__pycache__
+n8n-node
+n8n
+tests
+docs
+*.db
+.env

outreach_desk-2.0.0/.env.example

@@ -0,0 +1,22 @@
+# Copy to ~/.outreach-desk/.env (or ./.env) and fill in.
+
+# Claude writes the drafts. Required.
+ANTHROPIC_API_KEY=
+# OUTREACH_DESK_MODEL=claude-opus-5-5
+
+# Jev makes the decisions. Optional: without it, Claude Haiku answers the same questions.
+TYPESAFE_API_KEY=
+
+# Sending (SMTP) and replies (IMAP). Use an app password, ideally on a secondary address.
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=you@example.com
+SMTP_PASSWORD=
+IMAP_HOST=imap.gmail.com
+FROM_NAME=Your Name
+
+# Guard rails
+DAILY_CAP=30
+SEND_WINDOW=8-19
+# Required for sales mode (CAN-SPAM): your physical postal address.
+POSTAL_ADDRESS=

outreach_desk-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: pytest -q
+
+  n8n-node:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: n8n-node
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: lts/*
+          cache: npm
+          cache-dependency-path: n8n-node/package-lock.json
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run build

outreach_desk-2.0.0/.github/workflows/publish-n8n.yml

@@ -0,0 +1,33 @@
+# Push a tag like n8n-v1.0.1 to lint, build and publish n8n-nodes-outreach-desk to npm with a
+# provenance statement (required by n8n for community nodes since May 1 2026).
+# One-time setup: on npmjs.com add this repo + publish-n8n.yml as a Trusted Publisher,
+# or store an automation token as the NPM_TOKEN repository secret.
+name: Publish n8n node to npm
+
+on:
+  push:
+    tags: ["n8n-v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # npm provenance + trusted publishing
+      contents: read
+    defaults:
+      run:
+        working-directory: n8n-node
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: lts/*
+          registry-url: https://registry.npmjs.org
+          cache: npm
+          cache-dependency-path: n8n-node/package-lock.json
+      - name: Tag matches package.json version
+        run: test "${GITHUB_REF_NAME#n8n-v}" = "$(node -p "require('./package.json').version")"
+      - run: npm ci
+      - run: npm run release  # lint, build, npm publish with provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

outreach_desk-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+# Push a version tag (e.g. v2.0.1) to test, build and publish to PyPI via Trusted Publishing (no tokens).
+# The run finishes green only once pip can install the new version.
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # lets PyPI verify this workflow instead of a stored token
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev]' build
+      - run: pytest -q
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Wait until pip can install it  # PyPI's CDN can serve the old index for a few minutes after upload
+        run: |
+          for i in $(seq 30); do
+            pip download --no-deps --no-cache-dir -q -d /tmp/check "outreach-desk==${GITHUB_REF_NAME#v}" && exit 0
+            sleep 10
+          done
+          exit 1

outreach_desk-2.0.0/.gitignore

@@ -0,0 +1,11 @@
+.env
+__pycache__/
+*.pyc
+.DS_Store
+venv/
+.venv/
+.pytest_cache/
+dist/
+*.db
+n8n-node/node_modules/
+n8n-node/dist/

outreach_desk-2.0.0/Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY outreach_desk ./outreach_desk
+RUN pip install --no-cache-dir .
+ENV OUTREACH_DESK_HOME=/data
+VOLUME /data
+EXPOSE 8000
+CMD ["outreach-desk", "--host", "0.0.0.0", "--no-browser"]

outreach_desk-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Owen Alderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

outreach_desk-2.0.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: outreach-desk
+Version: 2.0.0
+Summary: A self-hosted outreach desk: Claude writes the emails, Jev makes the calls, you approve every send. With an n8n node.
+Project-URL: Homepage, https://github.com/owen-alderson/outreach-desk
+Author: Owen Alderson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,cold-email,crm,fastapi,htmx,jev,n8n,outreach,typesafe
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=1.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: system-one-adapter[anthropic]>=0.2
+Requires-Dist: typesafe-sdk>=0.7
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# outreach-desk
+
+**A self-hosted outreach desk. Claude writes the emails, Jev makes the calls, you approve every send.**
+
+Contacts, campaigns, follow-up sequences, reply triage, a pipeline board and analytics, in one
+`pipx install`. It plugs into n8n, so leads can flow in from a Google Sheet and hot replies can
+ping you on Slack.
+
+[![CI](https://github.com/owen-alderson/outreach-desk/actions/workflows/ci.yml/badge.svg)](https://github.com/owen-alderson/outreach-desk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/outreach-desk)](https://pypi.org/project/outreach-desk/)
+[![npm](https://img.shields.io/npm/v/n8n-nodes-outreach-desk?label=n8n%20node)](https://www.npmjs.com/package/n8n-nodes-outreach-desk)
+![License: MIT](https://img.shields.io/badge/license-MIT-blue)
+
+![outreach-desk demo: review queue, guardrail flags, approval, pipeline, analytics](docs/demo.gif)
+
+<sub>Screenshots use fictional demo data.</sub>
+
+## Why
+
+Most cold-email tools either write generic text and blast it, or leave you doing everything by
+hand. outreach-desk splits the work three ways:
+
+| | Who | What |
+|---|---|---|
+| **Writes** | Claude (`claude-opus-5-5`) | First emails and follow-ups, personalised **only** from facts you gave it about the recipient |
+| **Decides** | [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) (TypeSafe's System One model) | Typed, fast decisions with calibrated confidence: is this draft safe to send, how good a fit is this lead, what kind of reply is this |
+| **Approves** | You | Nothing is ever sent until you approve that exact draft |
+
+When Jev isn't confident, the decision goes to you instead of guessing.
+
+## What it does
+
+- **Contacts:** add by hand, import a CSV, or paste a LinkedIn bio and let Claude fill the form.
+  Each contact has a *facts* field, and drafts may only personalise from those facts.
+- **Campaigns:** two modes, **networking** (students and job-seekers writing to senior people)
+  and **sales** (B2B), with a sequence like `0, 4, 7` (first email, then follow-ups 4 and 7 days later).
+- **Review queue:** every draft arrives pre-checked by Jev. Edit, approve, regenerate or discard.
+- **Sending:** through your own mailbox over SMTP, threaded properly (`In-Reply-To`/`References`),
+  with a daily cap and a send window.
+- **Replies:** IMAP sync. **Any reply stops the sequence immediately.** Jev labels each reply
+  (`interested`, `meeting_request`, `referral`, `not_now`, `not_interested`, `out_of_office`,
+  `unsubscribe`, `bounce`) and moves the contact along the pipeline. Unsubscribes and bounces go
+  on a do-not-contact list. Out-of-office replies don't stop the sequence.
+- **Pipeline board:** `new → contacted → replied → meeting → won / lost`.
+- **Analytics:** reply rate and positive rate per campaign and per step, reply labels, and every
+  decision logged with which backend answered and how long it took.
+- **API + webhooks:** a bearer-key JSON API and HMAC-signed webhooks, used by the n8n node.
+
+## Quickstart
+
+```bash
+pipx install outreach-desk
+outreach-desk            # opens http://127.0.0.1:8000
+```
+
+Put your settings in `~/.outreach-desk/.env` (or a `.env` in the folder you run it from):
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...        # required: Claude writes the drafts
+TYPESAFE_API_KEY=                   # optional: Jev makes the decisions (see below)
+
+SMTP_HOST=smtp.gmail.com            # optional until you want to send
+SMTP_PORT=587
+SMTP_USER=you@example.com
+SMTP_PASSWORD=your-app-password     # an app password, not your login password
+IMAP_HOST=imap.gmail.com            # optional: reply sync
+FROM_NAME=Your Name
+
+DAILY_CAP=30
+SEND_WINDOW=8-19                    # local hours
+POSTAL_ADDRESS=                     # required for sales mode (CAN-SPAM footer)
+```
+
+Without SMTP settings you can still build contacts, campaigns and drafts; nothing will send.
+See [.env.example](.env.example) for every option.
+
+<details>
+<summary>Docker / Docker Compose (with n8n)</summary>
+
+```bash
+docker compose up -d     # outreach-desk on :8000, n8n on :5678 (both localhost-only)
+```
+
+The compose file reads `.env` if present and keeps data in named volumes.
+</details>
+
+## How Jev is used
+
+Jev is a *System One* model: you describe a decision as typed questions, and it answers each one
+with a probability or a label plus its confidence (TypeSafe quotes 70–500 ms per call). outreach-desk asks three
+sets of questions ([`decisions.py`](outreach_desk/decisions.py)):
+
+| Decision | Questions | What happens |
+|---|---|---|
+| **Draft guardrail** | `Noul`: uses a cliché? claims something about the recipient that isn't in their facts? unclear ask? · `Score`: tone fit | Flags shown on the draft with their probability. Advice only: you still decide. A plain banned-phrase check runs too, so exact matches are never missed. |
+| **Lead fit** | `Score` against the campaign's target · `Choice` seniority | Contacts sorted by fit |
+| **Reply triage** | `Choice` over the 8 reply labels | ≥ 70% confidence: routed automatically. Below that: it waits in the queue for you, though the sequence still stops |
+
+**No Jev key? It still works.** Without `TYPESAFE_API_KEY`, the same questions go to TypeSafe's
+open-source [`system-one-adapter`](https://github.com/typesafe-ai/system-one-adapter-python),
+which answers them with Claude Haiku 4.5 through the same interface. Expect it to be slower
+(seconds, not milliseconds); the Analytics page shows which backend answered each decision and
+how long it took, so you can compare.
+
+## n8n
+
+[`n8n-nodes-outreach-desk`](n8n-node/) adds two nodes to n8n:
+
+- **Outreach Desk:** create, update or list contacts; enrol contacts in a campaign; list,
+  approve (with edits) or reject drafts.
+- **Outreach Desk Trigger:** starts a workflow on `draft.ready`, `email.sent`,
+  `reply.classified` (optionally only for certain labels) or `contact.stage_changed`. It
+  registers its own webhook when the workflow is activated, removes it when deactivated, and
+  rejects any request without a valid signature.
+
+Install it from **Settings → Community Nodes** in n8n. Ready-made workflows in
+[`n8n/workflows/`](n8n/workflows/):
+
+| Template | Flow |
+|---|---|
+| [sheet-to-campaign](n8n/workflows/sheet-to-campaign.json) | New Google Sheet row → contact → campaign |
+| [hot-reply-to-slack](n8n/workflows/hot-reply-to-slack.json) | Interested / meeting / referral reply → Slack message |
+| [won-to-hubspot](n8n/workflows/won-to-hubspot.json) | Contact moved to *won* → HubSpot contact |
+
+## API
+
+Every endpoint needs `Authorization: Bearer <key>` (the key is on the Settings page) except
+`/api/health`.
+
+| Method | Path | |
+|---|---|---|
+| `GET` | `/api/contacts?stage=` | List contacts |
+| `POST` | `/api/contacts` | `{name, email, role?, company?, facts?}` |
+| `PATCH` | `/api/contacts/{id}` | Any field, or `stage` |
+| `GET` | `/api/campaigns` | List campaigns |
+| `POST` | `/api/campaigns/{id}/enroll` | `{contact_ids?: [...], emails?: [...]}` |
+| `GET` | `/api/drafts` | Drafts waiting for review |
+| `POST` | `/api/drafts/{id}/approve` | `{subject?, body?}` |
+| `POST` | `/api/drafts/{id}/reject` | Discards it and stops that contact's sequence |
+| `POST` / `DELETE` | `/api/webhooks[/{id}]` | Subscribe `{url, events}`; the response includes the signing secret |
+
+Webhook bodies are `{"event", "data", "sent_at"}` with
+`X-Outreach-Signature: sha256=HMAC_SHA256(secret, raw_body)`.
+
+## Safety rules
+
+These are enforced in code and covered by tests:
+
+- **Nothing sends without approval**, and an approved email that hasn't gone out yet is cancelled
+  if the person replies first.
+- **Daily cap and send window** for every mailbox.
+- **Do-not-contact list:** unsubscribes, bounces and contacts you delete are never emailed again.
+- **Sales mode** adds a postal address, an unsubscribe line and a `List-Unsubscribe` header.
+- **Delete a contact** removes their data (right to erasure) and keeps only their address on the
+  do-not-contact list.
+- **The app listens on localhost** with no login, and refuses form posts coming from other
+  websites. Don't expose it to the internet without putting authentication in front of it.
+
+Deliverability tip: send from a secondary address or domain, warm it up, and keep the daily cap low.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph desk[outreach-desk · FastAPI + SQLite + HTMX]
+    UI[Pages] --> Engine
+    API[JSON API] --> Engine
+    Scheduler[[every 60 s]] --> Engine
+    Engine --> Drafting[drafting.py]
+    Engine --> Decisions[decisions.py]
+    Engine --> Mail[mail.py]
+    Engine --> Hooks[webhooks.py]
+  end
+  Drafting -- writes --> Claude[(Claude API)]
+  Decisions -- decides --> Jev[(Jev / adapter)]
+  Mail -- SMTP / IMAP --> Mailbox[(Your mailbox)]
+  Hooks -- signed events --> n8n[(n8n)]
+  n8n -- API --> API
+```
+
+`engine.py` holds the rules (enrol, draft what's due, send what's approved, route replies). Every
+function takes a session and a clock, so it is fully testable without a network.
+
+## Development
+
+```bash
+git clone https://github.com/owen-alderson/outreach-desk && cd outreach-desk
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+pytest                    # 178 tests, no network: Claude, Jev, SMTP and IMAP are faked
+
+cd n8n-node && npm install && npm run lint && npm run build
+```
+
+Releases: push `vX.Y.Z` to publish to PyPI, `n8n-vX.Y.Z` to publish the n8n node to npm (both
+from GitHub Actions; the npm package carries a provenance statement).
+
+The original single-email Streamlit version is kept at tag
+[`v1-streamlit`](https://github.com/owen-alderson/outreach-desk/tree/v1-streamlit).
+
+## License
+
+MIT

outreach_desk-2.0.0/README.md

@@ -0,0 +1,203 @@
+# outreach-desk
+
+**A self-hosted outreach desk. Claude writes the emails, Jev makes the calls, you approve every send.**
+
+Contacts, campaigns, follow-up sequences, reply triage, a pipeline board and analytics, in one
+`pipx install`. It plugs into n8n, so leads can flow in from a Google Sheet and hot replies can
+ping you on Slack.
+
+[![CI](https://github.com/owen-alderson/outreach-desk/actions/workflows/ci.yml/badge.svg)](https://github.com/owen-alderson/outreach-desk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/outreach-desk)](https://pypi.org/project/outreach-desk/)
+[![npm](https://img.shields.io/npm/v/n8n-nodes-outreach-desk?label=n8n%20node)](https://www.npmjs.com/package/n8n-nodes-outreach-desk)
+![License: MIT](https://img.shields.io/badge/license-MIT-blue)
+
+![outreach-desk demo: review queue, guardrail flags, approval, pipeline, analytics](docs/demo.gif)
+
+<sub>Screenshots use fictional demo data.</sub>
+
+## Why
+
+Most cold-email tools either write generic text and blast it, or leave you doing everything by
+hand. outreach-desk splits the work three ways:
+
+| | Who | What |
+|---|---|---|
+| **Writes** | Claude (`claude-opus-5-5`) | First emails and follow-ups, personalised **only** from facts you gave it about the recipient |
+| **Decides** | [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev) (TypeSafe's System One model) | Typed, fast decisions with calibrated confidence: is this draft safe to send, how good a fit is this lead, what kind of reply is this |
+| **Approves** | You | Nothing is ever sent until you approve that exact draft |
+
+When Jev isn't confident, the decision goes to you instead of guessing.
+
+## What it does
+
+- **Contacts:** add by hand, import a CSV, or paste a LinkedIn bio and let Claude fill the form.
+  Each contact has a *facts* field, and drafts may only personalise from those facts.
+- **Campaigns:** two modes, **networking** (students and job-seekers writing to senior people)
+  and **sales** (B2B), with a sequence like `0, 4, 7` (first email, then follow-ups 4 and 7 days later).
+- **Review queue:** every draft arrives pre-checked by Jev. Edit, approve, regenerate or discard.
+- **Sending:** through your own mailbox over SMTP, threaded properly (`In-Reply-To`/`References`),
+  with a daily cap and a send window.
+- **Replies:** IMAP sync. **Any reply stops the sequence immediately.** Jev labels each reply
+  (`interested`, `meeting_request`, `referral`, `not_now`, `not_interested`, `out_of_office`,
+  `unsubscribe`, `bounce`) and moves the contact along the pipeline. Unsubscribes and bounces go
+  on a do-not-contact list. Out-of-office replies don't stop the sequence.
+- **Pipeline board:** `new → contacted → replied → meeting → won / lost`.
+- **Analytics:** reply rate and positive rate per campaign and per step, reply labels, and every
+  decision logged with which backend answered and how long it took.
+- **API + webhooks:** a bearer-key JSON API and HMAC-signed webhooks, used by the n8n node.
+
+## Quickstart
+
+```bash
+pipx install outreach-desk
+outreach-desk            # opens http://127.0.0.1:8000
+```
+
+Put your settings in `~/.outreach-desk/.env` (or a `.env` in the folder you run it from):
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...        # required: Claude writes the drafts
+TYPESAFE_API_KEY=                   # optional: Jev makes the decisions (see below)
+
+SMTP_HOST=smtp.gmail.com            # optional until you want to send
+SMTP_PORT=587
+SMTP_USER=you@example.com
+SMTP_PASSWORD=your-app-password     # an app password, not your login password
+IMAP_HOST=imap.gmail.com            # optional: reply sync
+FROM_NAME=Your Name
+
+DAILY_CAP=30
+SEND_WINDOW=8-19                    # local hours
+POSTAL_ADDRESS=                     # required for sales mode (CAN-SPAM footer)
+```
+
+Without SMTP settings you can still build contacts, campaigns and drafts; nothing will send.
+See [.env.example](.env.example) for every option.
+
+<details>
+<summary>Docker / Docker Compose (with n8n)</summary>
+
+```bash
+docker compose up -d     # outreach-desk on :8000, n8n on :5678 (both localhost-only)
+```
+
+The compose file reads `.env` if present and keeps data in named volumes.
+</details>
+
+## How Jev is used
+
+Jev is a *System One* model: you describe a decision as typed questions, and it answers each one
+with a probability or a label plus its confidence (TypeSafe quotes 70–500 ms per call). outreach-desk asks three
+sets of questions ([`decisions.py`](outreach_desk/decisions.py)):
+
+| Decision | Questions | What happens |
+|---|---|---|
+| **Draft guardrail** | `Noul`: uses a cliché? claims something about the recipient that isn't in their facts? unclear ask? · `Score`: tone fit | Flags shown on the draft with their probability. Advice only: you still decide. A plain banned-phrase check runs too, so exact matches are never missed. |
+| **Lead fit** | `Score` against the campaign's target · `Choice` seniority | Contacts sorted by fit |
+| **Reply triage** | `Choice` over the 8 reply labels | ≥ 70% confidence: routed automatically. Below that: it waits in the queue for you, though the sequence still stops |
+
+**No Jev key? It still works.** Without `TYPESAFE_API_KEY`, the same questions go to TypeSafe's
+open-source [`system-one-adapter`](https://github.com/typesafe-ai/system-one-adapter-python),
+which answers them with Claude Haiku 4.5 through the same interface. Expect it to be slower
+(seconds, not milliseconds); the Analytics page shows which backend answered each decision and
+how long it took, so you can compare.
+
+## n8n
+
+[`n8n-nodes-outreach-desk`](n8n-node/) adds two nodes to n8n:
+
+- **Outreach Desk:** create, update or list contacts; enrol contacts in a campaign; list,
+  approve (with edits) or reject drafts.
+- **Outreach Desk Trigger:** starts a workflow on `draft.ready`, `email.sent`,
+  `reply.classified` (optionally only for certain labels) or `contact.stage_changed`. It
+  registers its own webhook when the workflow is activated, removes it when deactivated, and
+  rejects any request without a valid signature.
+
+Install it from **Settings → Community Nodes** in n8n. Ready-made workflows in
+[`n8n/workflows/`](n8n/workflows/):
+
+| Template | Flow |
+|---|---|
+| [sheet-to-campaign](n8n/workflows/sheet-to-campaign.json) | New Google Sheet row → contact → campaign |
+| [hot-reply-to-slack](n8n/workflows/hot-reply-to-slack.json) | Interested / meeting / referral reply → Slack message |
+| [won-to-hubspot](n8n/workflows/won-to-hubspot.json) | Contact moved to *won* → HubSpot contact |
+
+## API
+
+Every endpoint needs `Authorization: Bearer <key>` (the key is on the Settings page) except
+`/api/health`.
+
+| Method | Path | |
+|---|---|---|
+| `GET` | `/api/contacts?stage=` | List contacts |
+| `POST` | `/api/contacts` | `{name, email, role?, company?, facts?}` |
+| `PATCH` | `/api/contacts/{id}` | Any field, or `stage` |
+| `GET` | `/api/campaigns` | List campaigns |
+| `POST` | `/api/campaigns/{id}/enroll` | `{contact_ids?: [...], emails?: [...]}` |
+| `GET` | `/api/drafts` | Drafts waiting for review |
+| `POST` | `/api/drafts/{id}/approve` | `{subject?, body?}` |
+| `POST` | `/api/drafts/{id}/reject` | Discards it and stops that contact's sequence |
+| `POST` / `DELETE` | `/api/webhooks[/{id}]` | Subscribe `{url, events}`; the response includes the signing secret |
+
+Webhook bodies are `{"event", "data", "sent_at"}` with
+`X-Outreach-Signature: sha256=HMAC_SHA256(secret, raw_body)`.
+
+## Safety rules
+
+These are enforced in code and covered by tests:
+
+- **Nothing sends without approval**, and an approved email that hasn't gone out yet is cancelled
+  if the person replies first.
+- **Daily cap and send window** for every mailbox.
+- **Do-not-contact list:** unsubscribes, bounces and contacts you delete are never emailed again.
+- **Sales mode** adds a postal address, an unsubscribe line and a `List-Unsubscribe` header.
+- **Delete a contact** removes their data (right to erasure) and keeps only their address on the
+  do-not-contact list.
+- **The app listens on localhost** with no login, and refuses form posts coming from other
+  websites. Don't expose it to the internet without putting authentication in front of it.
+
+Deliverability tip: send from a secondary address or domain, warm it up, and keep the daily cap low.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph desk[outreach-desk · FastAPI + SQLite + HTMX]
+    UI[Pages] --> Engine
+    API[JSON API] --> Engine
+    Scheduler[[every 60 s]] --> Engine
+    Engine --> Drafting[drafting.py]
+    Engine --> Decisions[decisions.py]
+    Engine --> Mail[mail.py]
+    Engine --> Hooks[webhooks.py]
+  end
+  Drafting -- writes --> Claude[(Claude API)]
+  Decisions -- decides --> Jev[(Jev / adapter)]
+  Mail -- SMTP / IMAP --> Mailbox[(Your mailbox)]
+  Hooks -- signed events --> n8n[(n8n)]
+  n8n -- API --> API
+```
+
+`engine.py` holds the rules (enrol, draft what's due, send what's approved, route replies). Every
+function takes a session and a clock, so it is fully testable without a network.
+
+## Development
+
+```bash
+git clone https://github.com/owen-alderson/outreach-desk && cd outreach-desk
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+pytest                    # 178 tests, no network: Claude, Jev, SMTP and IMAP are faked
+
+cd n8n-node && npm install && npm run lint && npm run build
+```
+
+Releases: push `vX.Y.Z` to publish to PyPI, `n8n-vX.Y.Z` to publish the n8n node to npm (both
+from GitHub Actions; the npm package carries a provenance statement).
+
+The original single-email Streamlit version is kept at tag
+[`v1-streamlit`](https://github.com/owen-alderson/outreach-desk/tree/v1-streamlit).
+
+## License
+
+MIT

outreach_desk-2.0.0/docker-compose.yml

@@ -0,0 +1,31 @@
+# outreach-desk + n8n, wired together.
+#   docker compose up -d
+# outreach-desk: http://localhost:8000    n8n: http://localhost:5678
+# Then in n8n: Settings → Community Nodes → install "n8n-nodes-outreach-desk", and create an
+# "Outreach Desk API" credential with base URL http://outreach-desk:8000 and the API key from
+# outreach-desk's Settings page. Workflow templates are in n8n/workflows/.
+services:
+  outreach-desk:
+    build: .
+    env_file:
+      - path: .env
+        required: false
+    ports:
+      - "127.0.0.1:8000:8000"  # localhost only: the pages have no login
+    volumes:
+      - desk-data:/data
+
+  n8n:
+    image: n8nio/n8n:latest
+    environment:
+      # Trigger webhooks are registered with this base URL, which the outreach-desk container can reach.
+      - WEBHOOK_URL=http://n8n:5678/
+      - N8N_SECURE_COOKIE=false
+    ports:
+      - "127.0.0.1:5678:5678"
+    volumes:
+      - n8n-data:/home/node/.n8n
+
+volumes:
+  desk-data:
+  n8n-data:

outreach_desk-2.0.0/outreach_desk/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("outreach-desk")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0"