# HyPeMa — Full Reference (single-file)

> Comprehensive machine-readable reference for LLMs and AI agents. Follows the llmstxt.org "full" convention: one file you can fetch once and have the complete picture. For the short index, see `/llms.txt`. For human-facing rendered docs, see `/docs/guide`, `/docs/mcp`, `/docs/api-reference`.

_Source of truth: this file + the markdown mirrors under `/docs/*.md`. Last updated: 2026-04-18._

---

## 1. Product summary

**HyPeMa** (short for **Hy**per **Pe**rsonalized **Ma**il) is an AI-powered cold-email outreach platform. It replaces the volume-era playbook (mass sends, burner domains, warmup pools, `{first_name}` templates, 1.7% reply rates) with a precision playbook: a few dozen individually-researched emails per week, drafted in the user's real Gmail, each one grounded in a specific current fact about the recipient's company.

Core promise: **one email per prospect, personally researched, sent from your Gmail.**

Why it works (quantified, sourced):
- **Gmail-native, not burners** — custom domain / webmail reply rate 4.2% vs 2.7% (State of Cold Email 2025).
- **Small batches > blasts** — ≤50-lead batches get 5.8% reply rate vs 2.1% for batches of 1,000+ (SoCE 2025).
- **Operator-quality copy** — "their company / your company" subject, usually under 100 words, why you first, then who is writing, one specific detail, one easy question, no meeting ask in the first email (Gong / 30MPC / Lavender benchmarks).

Positioning vs. mass-send / volume outbound stacks: HyPeMa optimizes for *replies*, not *send volume*. Different shape of tool for a different problem.

---

## 2. Company & legal

- **Operator:** OXO UG (haftungsbeschränkt)
- **Address:** Seehausen am Staffelsee, Germany
- **Founder:** Robert Stammen (solo)
- **Jurisdiction:** German (EU)
- **Data hosting:** Supabase EU-Frankfurt (prospect + account data never leaves EU infrastructure)
- **Compute:** Cloudflare Workers (backend + MCP server)
- **Payments (MoR):** Polar.sh (handles EU VAT + sales tax; migration to Dodo Payments in progress)
- **AI provider:** Anthropic (Claude models, streaming SSE)
- **Auth:** Google OAuth via Supabase Auth; public API uses Bearer API keys (`hpm_live_…`)

Contact:
- `support@hypema.app` — product & support
- `service@hypema.app` — business, legal, billing questions

Legal pages:
- `/privacy` — GDPR privacy policy
- `/terms` — terms of service (DPA linked at `/terms#dpa`)
- `/imprint` — German Impressum
- `/cookies` — cookie policy

---

## 3. Pricing

All prices are EUR, excluding VAT. VAT is added at checkout for EU customers (handled by Polar as MoR).

| Plan | Price | Tokens | Notes |
|------|-------|--------|-------|
| **Free** | €0 forever | 500 one-time credit on signup (no monthly reset) | No credit card. Uncapped lead count. Full feature access: AI lead research, email drafting, Chrome extension, REST API, MCP. |
| **Pro (monthly)** | €49/mo | 5,000/mo | Unlimited campaigns, priority support, buy extra token packs anytime. |
| **Pro (yearly)** | €441/yr (25% off) | 5,000/mo | Same Pro features, billed annually. |

**Token packs** (Pro subscribers, never expire, kick in after monthly allowance):
- 5,000 tokens — €50
- 25,000 tokens — €250
- 500,000 tokens — €5,000

**Approximate token costs** (low Thinking Depth, Secret Sauce off):
- Email generation: ~4 tokens/email
- Lead research: ~10–30 tokens/lead
- Company research: ~5–15 tokens/call
- CRUD (list/create/update/delete leads, groups, campaigns): free
- Usage check (`GET /usage` or `check_usage` MCP tool): free

100 tokens ≈ €1 + VAT.

---

## 4. Three-step core flow

### Step 1 — Find leads

Sources:
- **AI generation** — describe target criteria (industry, role, region, company size). AI searches the web and returns real people with verified email addresses. Duration depends on Thinking Depth (3–15 min).
- **CSV import** — upload `.csv`/`.xlsx`/`.xls` up to 10 MB. AI auto-maps columns (first header row used). Recognized fields: `email` (required), `firstName`, `lastName`, `company`, `roleTitle`, `country`, `notes`.
- **Manual entry** — add leads one at a time.

Leads are organized into **lead groups** (e.g., "Munich Accountants", "Chicago Lawyers"). Every group has a source tag: `ai` | `csv` | `manual`.

### Step 2 — Draft emails

UI: n8n-style formula bar linking Sender → Topic/Goal → Leads → Settings → Draft Emails. The user:
1. Selects a lead group.
2. Confirms sender context (name, role, company — pulled from onboarding, editable).
3. Writes a short "topic & goal" sentence (min 10 chars, e.g. "Introducing our AI bookkeeping software to DACH restaurant owners, book a short call").
4. Picks Secret Sauce (on/off) and Thinking Depth (or inherits tenant defaults).
5. Optionally generates 3 sample previews, iterates with text feedback, regenerates.
6. Clicks **Draft Emails** to batch-generate one email per lead. A campaign is auto-created.

### Step 3 — Review & send

Gmail-style inbox of drafted emails. Each row expands to an editable subject + body, with feedback field and two buttons: **Rewrite This Draft** and **Rewrite All Drafts**. Clicking **Send via Gmail** calls the Chrome extension's bridge (`sendDraftRequest`), which opens a Gmail compose window and fills it with the payload. The user still clicks Send in Gmail — HyPeMa never sends on their behalf.

After sending, the dashboard's reply-sync button (Chrome extension scans Gmail inbox threads) matches replies to leads and updates campaign stats. Reply tracking updates: total leads, emails generated, emails sent, replies received, reply rate %.

---

## 5. Secret Sauce (on or off)

HyPeMa's source-verified cold-email playbook, injected into the AI prompt at generation time. It doesn't change the user's pitch — it changes *how* the AI structures and phrases the email. Every rule is verified at its primary source.

| Setting | Value string | Tokens/email (varies by depth) | What it does |
|------|--------------|-------------------------------|----------|
| **On** | `reply_rate` (canonical; `positive_reply_rate` is a legacy alias with the same effect) | ~5–8 (Low–High), ~13 xhigh, ~31 max | Secret Sauce 2.2, rebuilt from fresh 2026 research: why this recipient up front, then who is writing, at most one dated research fact, one easy interest question (or an offer of something concrete from the sender's inputs), no meeting asks, nothing about the sender beyond the sender's inputs, form of address by the recipient's country and industry, usually under 100 words. |
| **Off** | `none` | ~4 (Low–High), ~8 xhigh, ~21 max | Compact Secret Sauce 2.2: the same rules in a shorter prompt. Lowest cost per email. High-volume campaigns. |

Configuration precedence:
1. **Per-request** (`secretSauceVariant` in API/MCP) — highest priority
2. **Per-campaign** (override in Draft Emails UI)
3. **Tenant default** (Settings → Secret Sauce)
4. **Ask every time** (tenant setting: force per-campaign choice)

A fourth tenant-level value `ask_every_time` forces the user to pick per campaign.

Estimated emails per 5,000 tokens (Pro monthly allowance; from the 75-run measured matrix — a re-benchmark of the unified Sauce is pending):

| Sauce | Low depth | Medium | High | Max |
|-------|-----------|--------|------|-----|
| Off | ~1,250 | ~1,250 | ~1,250 | ~240 |
| On | ~625–1,000 | ~625–1,000 | ~625–1,000 | ~160 |

---

## 6. Thinking Depth (four AI effort levels, per operation)

Controls the model's reasoning effort (Claude Opus 5.5 for emails, GPT-6 Luna for lead search, research and CSV mapping). Higher levels = more reasoning tokens (billed as output) = better results but more cost and latency. Each operation (Email, Lead Generation, Company Research, CSV Mapping) has its own tab in Settings → General.

| Level | Value | Email tokens | Email time | Lead gen time (10 leads) | Company research time |
|-------|-------|--------------|------------|---------------|----------------------|
| **Low** | `low` | ~4–8 | ~6–7 sec | ~4–7 min | ~30 sec |
| **Medium** | `medium` | ~4–8 | ~6–9 sec | ~3–6 min | ~1 min |
| **High** (default) | `high` | ~4–8 | ~7–21 sec | ~4–8 min | ~3 min |
| **Extra High** | `xhigh` | ~8–13 | ~17–39 sec | ~6–12 min | ~4 min |
| **Max** | `max` | ~21–31 | ~45 sec–2 min | ~8–15 min | ~5 min |

**Default effort is `high`** for every operation: email writing runs on Claude Opus 5.5; lead generation, company research, lead enrichment and CSV mapping run on GPT-6 Luna. Email numbers measured 2026-04-19 via a 75-run benchmark (5 profile-pairs × 3 pre-unification sauce variants × 5 efforts); a re-benchmark of the unified Secret Sauce is pending. Lead gen times measured 2026-10-01 on GPT-6 Luna for 10 leads; a search needs 1–3 rounds, and lower levels return fewer leads per round, so Low is not the fastest. Company research times are older estimates.

CSV mapping runs in 5–30 sec regardless.

API/MCP: pass `effort` on any AI endpoint to override the per-operation default for a single request.

---

## 7. MCP server (17 tools)

- **URL:** `https://mcp.hypema.app/mcp`
- **Transport:** Streamable HTTP (MCP spec)
- **Auth:**
  - **OAuth 2.1** (recommended for Claude.ai, ChatGPT, Claude Desktop) — sign in with HyPeMa or Google account, approve access.
  - **API key** (Cursor, VS Code, CLI) — `Authorization: Bearer hpm_live_…` from Settings → API Keys.
- **Shared pool:** MCP and web-app share the same data, tokens, and rate limits.

### Tool inventory (15)

Annotated shape: `{ name, type, destructive?, read_only?, cost, description }`.

**AI operations:**
1. `research_company` — AI, read-only, ~25–40 tokens. Research a company by URL. Params: `url` (string, required); `effort` (optional). Returns the company profile (name, the sender person and company texts, a suggested outreach angle), usually within 40 seconds; a research that takes longer keeps running in the background and returns a `job_id` instead.
   - `get_company_research` — read-only, free. Params: `job_id` (optional), `wait_seconds` (0–45, default 45). Waits for the research, then returns its result, its progress while it runs, or the error. Without `job_id`, lists the 5 most recent researches.
2. `generate_leads` — AI, not read-only, ~3–5 tokens per lead found. Web-search for leads matching given criteria. Params: `industry` (required); `roleTitle`, `region`, `count` (1–100, default 5), `companySize`, `effort` (all optional). Runs in the background (usually 3–8 minutes, at most 15) because MCP clients end a tool call after 1–3 minutes: returns a `job_id` within seconds, and an identical request while it runs returns the same job. The finished search creates a new lead group.
   - `get_lead_search` — read-only, free. Params: `job_id` (optional), `wait_seconds` (0–45, default 45). Waits for the search, then returns its leads (with `leadGroupId`), its progress while it runs, or the error. Without `job_id`, lists the 5 most recent searches.

**Lead CRUD (free):**

`create_lead` requires `email` and `company`. `first_name` and `last_name` are optional. Use `lead_type` (`person`, `role_inbox`, `company_inbox`) and never invent a person name for role or company inboxes.
3. `list_leads` — read-only. Filter by `status` (`new|generated|drafted|sent`), `search`, paginate via `page` / `per_page`.
4. `get_lead` — read-only. By `id`.
5. `create_lead` — write. Single lead, optionally assigned to `leadGroupId`.
6. `update_lead` — write. Patch any field; `status` transitions leads through the pipeline.
7. `delete_lead` — destructive, write. Irreversible.

**Email operations:**

`get_draft_payload` returns both plain text and HTML bodies: `textBody` and `htmlBody`. The legacy `body` field is also present for compatibility.
8. `preview_emails` — AI, read-only, ~4–8 tokens/preview. Generate 1–10 sample previews without saving. Supports `feedbackHistory[]` for iteration, `secretSauceVariant`, `effort`. Returns `{previews[], count}`.
9. `generate_email` — AI, write, ~4–8 tokens. One email for one lead. Saves to DB, marks lead as `generated`, auto-creates a campaign if none provided. Supports `feedbackHistory`, `secretSauceVariant`, `effort`.
10. `generate_email_batch` — AI, write, ~4–8 tokens/lead. Generate for every lead in a group. Supports `perLeadVariants` for per-lead Sauce overrides, `effort` batch-wide.
11. `get_draft_payload` — utility, write. Validates the email hasn't expired and recipient isn't suppressed, marks lead as `drafted`, returns `{provider, to, subject, body}` ready to hand to a Gmail or Outlook MCP (or any email-sending MCP) to actually create the draft or send.

**Campaign CRUD (free):**
12. `list_campaigns` — read-only. All campaigns with inline stats (leadCount, emailsGenerated, emailsSent, repliesReceived, replyRate).
13. `get_campaign` — read-only. Single campaign with stats.
14. `get_campaign_stats` — read-only. Just the aggregate metrics.

**Utility (free):**
15. `check_usage` — read-only. Current token balance, `used`, `limit`, `remaining`.

### Sending emails with MCP

HyPeMa's MCP **does not send email directly**. Two paths:

**Path A — Web-app + Chrome extension.** Emails generated via MCP appear in the user's web-app workspace. The user opens the campaign and uses the Chrome extension to create Gmail drafts. Same flow as the web-app UI.

**Path B — Chain with an email MCP.** Call `get_draft_payload` to get `{provider, to, subject, body}`, then pass to any email MCP that can create drafts or send (Gmail or Outlook over Microsoft Graph being the typical choices). Full automation from inside Claude/ChatGPT/Cursor.

Typical chain:
```
preview_emails → (iterate with feedback) → generate_email_batch → get_draft_payload → Gmail/Outlook MCP
```

### Setup per client (commands/snippets)

**Claude.ai (Web).** Settings → Connectors → Add custom connector → `https://mcp.hypema.app/mcp`. Sign in with HyPeMa or Google. Paid Claude plan required for custom connectors (Pro/Max/Team/Enterprise).

**Claude Desktop (GUI).** Settings → Connectors → Add custom connector → same URL. Or edit `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "hypema": {
      "url": "https://mcp.hypema.app/mcp",
      "headers": { "Authorization": "Bearer hpm_live_your_key_here" }
    }
  }
}
```

**Claude Code (CLI).**
```bash
claude mcp add hypema --transport http https://mcp.hypema.app/mcp
# or with API key:
claude mcp add hypema \
  --transport http \
  --header "Authorization: Bearer hpm_live_your_key_here" \
  https://mcp.hypema.app/mcp
```

**ChatGPT.** Developer Mode required (Pro/Team/Enterprise/Edu). Settings → Apps & Connectors → Add → name `HyPeMa`, URL `https://mcp.hypema.app/mcp`. Sign in + approve.

**Cursor.** `.cursor/mcp.json` in project root:
```json
{
  "mcpServers": {
    "hypema": {
      "url": "https://mcp.hypema.app/mcp",
      "headers": { "Authorization": "Bearer hpm_live_your_key_here" }
    }
  }
}
```

**VS Code / GitHub Copilot.** Settings (JSON):
```json
{
  "mcp": {
    "servers": {
      "hypema": {
        "type": "http",
        "url": "https://mcp.hypema.app/mcp",
        "headers": { "Authorization": "Bearer hpm_live_your_key_here" }
      }
    }
  }
}
```

**Windsurf / Codeium.**
```json
{
  "mcpServers": {
    "hypema": {
      "serverUrl": "https://mcp.hypema.app/mcp",
      "headers": { "Authorization": "Bearer hpm_live_your_key_here" }
    }
  }
}
```

**OpenAI Agents SDK (Python).**
```python
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp.hypema.app/mcp",
        "authorization": { "token": "Bearer <your_oauth_token>" }
    }],
    input="Find 5 CTOs at fintech companies in Germany"
)
```

Also supported (same URL, API key in Authorization header): **JetBrains IDEs, Zed, Cline, Goose, OpenClaw, Google Gemini (ADK)**.

---

## 8. REST API v1 (20 endpoints)

**Base URL:** `https://hypema.app/api/v1`
**Auth:** `Authorization: Bearer hpm_live_…` (API key) or Supabase OAuth JWT
**Content type:** `application/json`
**Response envelope:**
```json
{
  "data": {...} | [...] | null,
  "error": null | { "code": "...", "message": "..." },
  "meta": { "requestId": "req_...", "tokensConsumed": 0, "pagination": {...}, "tokensRemaining": 0 }
}
```

**Rate limiting:** complexity-based. Cost weights: read=1, write=2, AI single=5, AI heavy=10–15. Free 100 pts/min, Pro 500 pts/min. Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Cost`.

**Error codes:**
- `400 VALIDATION_ERROR` — invalid request
- `401 UNAUTHORIZED` — missing/invalid API key
- `403 TOKEN_LIMIT_EXCEEDED` — out of tokens
- `404 NOT_FOUND` — resource not found
- `429 RATE_LIMITED` — rate limit exceeded
- `500 INTERNAL_ERROR` — server error

### Parameter enums (canonical — apply to both REST API and MCP tools)

Every parameter below is a strict enum. Servers reject any value not on the list with `400 VALIDATION_ERROR`. Enum values are case-sensitive.

| Parameter | Allowed values | Used by |
|---|---|---|
| `effort` | `"max"` \| `"xhigh"` \| `"high"` \| `"medium"` \| `"low"` | `/ai/research-company`, `/ai/generate-leads`, `/emails/generate`, `/emails/generate-preview`, `/emails/generate-batch`, and the matching MCP tools (`research_company`, `generate_leads`, `generate_email`, `preview_emails`, `generate_email_batch`). `"xhigh"` and `"max"` are **Opus 4.7+ only** (earlier models reject them). Omit to use the per-operation tenant default. |
| `secretSauceVariant` | `"reply_rate"` \| `"positive_reply_rate"` \| `"none"` | `/emails/generate`, `/emails/generate-preview`, `/emails/generate-batch`, and the matching MCP tools. Since the Sauce unification, `"reply_rate"` (canonical) and `"positive_reply_rate"` are legacy aliases that both resolve to the same unified Secret Sauce (on). Omit to use the tenant default. `"none"` explicitly disables the sauce (off) even if the tenant default has it on. |
| `perLeadVariants[]` | Array of `secretSauceVariant` values, one per lead in order | `/emails/generate-batch` body and `generate_email_batch` MCP tool. `null` elements inherit the tenant default. |
| Lead `status` (filter + update) | `"new"` \| `"generated"` \| `"drafted"` \| `"sent"` \| `"replied"` \| `"bounced"` | `GET /leads` (query-string filter), `PATCH /leads/:id` (transition), `list_leads` / `update_lead` MCP tools. Pipeline order is new → generated → drafted → sent → (replied \| bounced). |
| Lead group `source` | `"manual"` \| `"csv"` \| `"ai"` | `POST /lead-groups` body. `"ai"` groups are created automatically by `generate_leads`. |
| Error `code` (response `error.code`) | `"VALIDATION_ERROR"` \| `"UNAUTHORIZED"` \| `"TOKEN_LIMIT_EXCEEDED"` \| `"NOT_FOUND"` \| `"RATE_LIMITED"` \| `"INTERNAL_ERROR"` | Every non-2xx response body |
| Tenant-level effort settings (`aiThinkingEffort`, `aiEffortLeadGen`, `aiEffortResearch`, `aiEffortCsvMapping`) | Same as `effort` enum above, plus `"ask_every_time"` on `aiThinkingEffort` only | `PATCH /tenants/current` (web-app owners only). `"ask_every_time"` forces a per-campaign choice for email generation. |

### AI operations (SSE-capable)

**`POST /ai/research-company`** — research a company URL. Body: `{url, effort?}`. 30s–5min. Returns `{companyName, description, industry, productName, valueProposition, targetAudience, ceoName, ceoRole}`. ~5–15 tokens.

**`POST /ai/generate-leads`** — find leads. Body: `{industry, roleTitle?, region?, count?, companySize?, excludeGroupIds?, effort?}`. 30s–5min. Returns `{leads[], count, leadGroupId}`. ~10–30 tokens.

### Email operations

**`POST /emails/generate-preview`** — preview samples without saving. Body: `{leadGroupId, topicGoalText?, feedbackHistory?[], sampleCount?, leadIds?[], secretSauceVariant?, effort?}`. Returns `{previews[], count}`.

**`POST /emails/generate`** — one email for one lead. Body: `{leadId, topicGoalText, feedbackHistory?[], secretSauceVariant?, effort?}`. Returns `{id, subject, body, unsubscribeUrl, campaignId}`.

**`POST /emails/generate-batch`** — batch generation for a lead group. Body: `{leadGroupId, topicGoalText?, feedbackHistory?[], leadIds?[], secretSauceVariant?, perLeadVariants?[], effort?}`. Returns `{results[], failedLeads[]}`.

**`GET /emails/:id`** — fetch a generated email. Returns `{id, leadId, subject, body, unsubscribeUrl}`.

**`POST /emails/drafts/payload`** — build a send-ready payload. Body: `{leadId, generatedEmailId}`. Validates expiry + suppression, marks lead `drafted`. Returns `{provider, to, subject, body}`.

### Leads CRUD

**`GET /leads`** — query params `page`, `per_page` (max 100), `status`, `search`. Returns paginated list.

**`POST /leads`** — body: `{email, firstName?, lastName?, company?, roleTitle?, country?, sourceUrl?, notes?, leadGroupId?}`.

**`GET /leads/:id`** / **`PATCH /leads/:id`** / **`DELETE /leads/:id`** — CRUD by UUID.

### Lead groups

**`GET /lead-groups`** — list with `leadCount` per group.

**`POST /lead-groups`** — body: `{name, source?}` (source: `manual` | `csv` | `ai`).

**`GET /lead-groups/:id/leads`** — leads in a group.

### Campaigns

**`GET /campaigns`** — list with inline stats.

**`GET /campaigns/:id`** — single campaign.

**`GET /campaigns/:id/stats`** — `{totalLeads, emailsGenerated, emailsSent, repliesReceived, replyRate}`.

**`GET /campaigns/:id/emails`** — query `status=sent,replied`. Returns `[{leadId, email, firstName, lastName, company, roleTitle, status, sentAt, repliedAt, replySnippet, subject, body}, …]`.

### Usage

**`GET /usage`** — `{allowed, used, limit, remaining}`.

### Example: full end-to-end via cURL

```bash
# 1. Research a company
curl -X POST https://hypema.app/api/v1/ai/research-company \
  -H "Authorization: Bearer hpm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://stripe.com"}'

# 2. Find 5 leads
curl -X POST https://hypema.app/api/v1/ai/generate-leads \
  -H "Authorization: Bearer hpm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"industry": "your target industry", "roleTitle": "decision-maker role", "region": "Berlin", "count": 5}'

# 3. Preview 3 sample emails (iterate with feedback, no tokens committed to batch)
curl -X POST https://hypema.app/api/v1/emails/generate-preview \
  -H "Authorization: Bearer hpm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "leadGroupId": "group-uuid",
    "topicGoalText": "Introducing our AI payments infra; want a 10-min exploratory call",
    "sampleCount": 3,
    "secretSauceVariant": "reply_rate",
    "effort": "high"
  }'

# 4. Batch-generate for the whole group
curl -X POST https://hypema.app/api/v1/emails/generate-batch \
  -H "Authorization: Bearer hpm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"leadGroupId": "group-uuid", "topicGoalText": "...", "secretSauceVariant": "reply_rate"}'

# 5. Build send-ready payload for one lead
curl -X POST https://hypema.app/api/v1/emails/drafts/payload \
  -H "Authorization: Bearer hpm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"leadId": "lead-uuid", "generatedEmailId": "email-uuid"}'

# 6. Check campaign reply rate
curl https://hypema.app/api/v1/campaigns/campaign-uuid/stats \
  -H "Authorization: Bearer hpm_live_your_key_here"
```

---

## 9. Public site map (what crawlers should index)

**Landing / marketing:**
- `/` — current homepage
- `/agents` — agent-first landing page: MCP and REST as the delivery surface
- `/v30` — precision manifesto ("Seven Laws of Reply"); canonicalises to `/`, so it is
  crawlable but deliberately absent from the sitemap

**Public documentation (rendered React):**
- `/docs/guide` — web-app guide
- `/docs/mcp` — MCP integration guide
- `/docs/api-reference` — REST API reference

**Public documentation (markdown mirrors, no JS):**
- `/docs/guide.md`
- `/docs/mcp.md`
- `/docs/api-reference.md`

**Legal:**
- `/privacy`, `/terms`, `/imprint`, `/cookies`

**Auth & app (blocked for crawlers — redirect to login, no content):**
- `/login`, `/auth/callback`, `/oauth/consent`
- `/onboarding*`, `/dashboard`, `/settings*`, `/leads`, `/draft-emails`, `/review-send`
- `/campaign/*`, `/academy/*` (in-app, requires auth)
- `/control-center/*` (admin only)

**Machine-readable:**
- `/robots.txt`, `/sitemap.xml`, `/llms.txt`, `/llms-full.txt`
- `/.well-known/ai.txt`, `/.well-known/security.txt`, `/humans.txt`

---

## 10. Chrome extension

**Chrome Web Store:** `https://chromewebstore.google.com/detail/hypema-%E2%80%94-precise-email-ou/apnbcdldkcamjajnlmcifgeabhemonpf`

**Architecture:**
```
HyPeMa web app  →  Chrome extension  →  Gmail
   postMessage         opens compose
```

**What it does:**
- Listens for `postMessage` from the HyPeMa web app.
- On a `sendDraftRequest`, opens Gmail compose and fills `to` / `subject` / `body`.
- On `syncReplies`, scans Gmail inbox for thread subjects matching sent leads, reports back.

**What it does NOT do:**
- Never sends an email automatically (user must click Send in Gmail).
- Never reads inbox content outside the scoped subject-match scan the user explicitly triggers.
- Never stores email content locally beyond the ephemeral compose payload.

**Permissions:** `gmail.google.com/mail/u/0/*` (compose + read subjects for reply sync).

---

## 11. Canonical outbound-email format

Every email HyPeMa writes follows these rules (distilled from Lavender / Outbound Squad / The Modern Seller / Gong 28M-email dataset):

- **Subject:** "their company / your company", with the names people use (Adobe, not Adobe Inc.).
- **Body:** usually under 100 words, a few short paragraphs, plain text.
- **Tone:** direct and courteous; the form of address follows the recipient's country and industry. Never "hope this finds you well", "I hope you're doing well", "I came across…".
- **Opening:** starts with why this recipient gets the email, then says who is writing, with at most one specific detail from the research (a hiring post, a product launch, a funding round, a blog post — anything recent and public); a time-sensitive fact is given with its date.
- **Proof line:** at most one, only when the sender's inputs contain a real one, copied exactly; no logo name-drops.
- **CTA:** binary, easy-to-answer, no calendar link, no meeting ask in the first email. "Worth a quick look?" / "Does this resonate?" / "Is this still a priority?"
- **Product mention:** by name in the opening, no feature list.
- **Claims about you:** only what your inputs say, at the strength they say it.

Variables the AI has access to:
- `{{recipientFirstName}}` `{{recipientLastName}}` `{{recipientEmail}}` `{{recipientCompany}}` `{{recipientRole}}` `{{recipientCountry}}` `{{recipientNotes}}`
- `{{senderPersonText}}` `{{senderCompanyText}}` `{{topicGoalText}}`
- `{{feedbackHistory}}` — cumulative user feedback across iterations

---

## 12. Key FAQ (verbatim from current homepage / docs)

**Does HyPeMa send emails?**
No. HyPeMa writes drafts in your Gmail. You review each email and click send yourself. Your domain reputation stays clean because the emails come from you.

**How many tokens does each action cost?**
Roughly 15 tokens to write one personalized email. Roughly 30 tokens to find and research one lead. The 500-token free plan is enough to run a real campaign end-to-end.

**Do I need the Chrome extension?**
Yes — it is how drafts are created inside your Gmail. It only writes drafts. It never reads your existing emails, contacts or anything else.

**Which email providers are supported?**
Gmail (Google Workspace and personal Gmail). Outlook support is on the roadmap.

**How many leads per campaign?**
Typically 10–50. HyPeMa is built for precision: each email is individually researched. You do not need 10,000 leads when 40 land 8+ meetings.

**Can I cancel anytime?**
Yes. Cancellation takes effect at the end of the current billing period. See Terms for details on renewals and refund policy.

**Is HyPeMa GDPR compliant?**
Yes. Minimal data processed, nothing sold or shared, storage in EU-Frankfurt (Supabase). See Privacy Policy for the full picture.

**Won't AI emails sound robotic?**
67% of buyers don't mind AI-assisted emails when they're relevant (State of Cold Email 2025). HyPeMa ships with built-in copywriting rules distilled from Lavender, Outbound Squad, and Gong — the same rules top performers use manually.

**What about deliverability?**
It's your Gmail. Same reputation as your work email. No new domain, no warmup, no spam-folder roulette.

**I already use a mass-send outbound stack.**
Those scale volume. HyPeMa scales quality. Export leads from anywhere — HyPeMa turns them into real drafts in your real Gmail.

---

## 13. Tech stack

| Layer | Technology |
|-------|-----------|
| Frontend | React 19, Vite, React Router 7, TailwindCSS + DaisyUI, Framer Motion animations |
| Backend | Express.js (Node 22), Cloudflare Workers (via Wrangler), Zod validation |
| MCP server | Cloudflare Worker, Streamable HTTP transport, Partyserver SDK |
| Database | Supabase (PostgreSQL, EU-Frankfurt), Row Level Security |
| Auth | Google OAuth via Supabase Auth; API keys (`hpm_live_…`) for public API/MCP |
| AI | Anthropic Claude API (streaming SSE), web_search tool for research |
| Payments | Polar.sh (MoR, handles VAT); Dodo migration in progress |
| Extension | Chrome MV3, content scripts for Gmail compose + reply scan |

---

## 14. Endpoint & URL cheat sheet

| What | Where |
|------|-------|
| Website | https://hypema.app |
| Sign up / login | https://hypema.app/login |
| Pricing | https://hypema.app/#pricing |
| Web-app guide | https://hypema.app/docs/guide — markdown: `/docs/guide.md` |
| MCP guide | https://hypema.app/docs/mcp — markdown: `/docs/mcp.md` |
| REST API reference | https://hypema.app/docs/api-reference — markdown: `/docs/api-reference.md` |
| MCP server | https://mcp.hypema.app/mcp |
| REST API base | https://hypema.app/api/v1 |
| API-key management | https://hypema.app/settings/api-keys |
| Chrome extension | https://chromewebstore.google.com/detail/apnbcdldkcamjajnlmcifgeabhemonpf |
| Support email | support@hypema.app |
| Business email | service@hypema.app |

---

_End of full reference. Questions? Fetch the per-topic markdown docs or email support@hypema.app._