# HyPeMa

> HyPeMa is an AI-powered SaaS platform for hyper-personalized cold email outreach. AI researches each prospect on the open web, writes a unique 1-of-1 email per lead, and delivers it as a draft in the user's real Gmail via a Chrome extension. A remote MCP server and REST API let AI agents drive the whole workflow from Claude, ChatGPT, Cursor, and other clients.

Need depth? Start here, then fetch `/llms-full.txt` for the comprehensive single-file reference, or the per-topic markdown mirrors under `/docs/*.md`.

## What HyPeMa does (in one paragraph)

HyPeMa replaces the volume-era cold-email playbook (burner domains, warmup, merge-tag templates, 1.7% reply rates) with a precision playbook: a few dozen researched emails per week, sent from the user's real Gmail, each one grounded in a specific, current thing about the recipient's company. Pricing is token-based to enforce quality over volume. EU-hosted (Supabase Frankfurt), GDPR-compliant, no data resale.

## Core user flow (3 steps)

1. **Find leads** — AI searches the open web for prospects matching given criteria (industry, role, region, company size), or the user imports a CSV, or adds leads manually. Leads are grouped into lead-lists.
2. **Draft emails** — user picks a lead group, writes a short "topic & goal" sentence, optionally previews sample emails and iterates via feedback, then batch-generates a unique email per lead. Secret Sauce (copywriting mode) and Thinking Depth (reasoning effort) are configurable.
3. **Review & send** — the Chrome extension places each email as a draft in the user's Gmail. The user reviews, edits inline, and sends from their real inbox. Reply tracking scans Gmail for responses and rolls them up per campaign.

## Secret Sauce — three copywriting modes

Proprietary copywriting intelligence applied during email generation. Set a global default in Settings, override per-campaign, or per-request via `secretSauceVariant` in the API/MCP.

| Mode | Tokens/email | Optimizes for |
|------|--------------|---------------|
| `reply_rate` | ~5–30 | Maximize any response (curiosity hooks, open loops, easy question). Best for awareness, networking, research outreach. |
| `positive_reply_rate` | ~8–51 | Maximize interested replies (outcome framing, objection preemption, low-commitment CTA). Best for sales, partnerships, recruiting. |
| `none` (Cost-efficient) | ~5–25 | Standard personalized AI copy without Sauce enhancement. Lowest cost per email. |

## Thinking Depth — four AI effort levels

Configurable per operation (Email, Lead Generation, Company Research, CSV Mapping) in Settings. API/MCP accept an `effort` parameter per request.

| Level | Email tokens | Email duration | Notes |
|-------|--------------|----------------|-------|
| `low` | ~4–6 | ~6–7 sec | Fastest, cheapest — ideal for high-volume campaigns. |
| `medium` | ~4–6 | ~6–9 sec | Adaptive thinking usually skips for cold emails; behaves like `low` at this task. |
| `high` (default) | ~4–12 | ~7–21 sec | Deep reasoning, quality-focused outreach. |
| `xhigh` | ~8–18 | ~17–39 sec | Extra-high between `high` and `max`. **Opus 4.7 only.** |
| `max` | ~21–52 | ~45 sec–2 min | No constraints on thinking depth. **Opus 4.7 only.** High-value outreach. |

Lead Generation, Company Research, and CSV Mapping have matching levels with their own durations (see `/docs/guide.md#thinking-depth`).

## MCP Server

Remote Model Context Protocol server exposing **15 tools** to any MCP-compatible AI assistant.

- **URL:** `https://mcp.hypema.app/mcp`
- **Transport:** Streamable HTTP
- **Auth:** OAuth 2.1 (Claude.ai, ChatGPT, Claude Desktop) or API key (Cursor, VS Code, CLI) via `Authorization: Bearer hpm_live_…`

### Tools

AI operations:
- `research_company` — research a company URL with AI web search (~25–40 tokens)
- `generate_leads` — find real prospects matching given criteria (~30–60 tokens)

Email operations:
- `preview_emails` — draft preview samples without saving (supports `feedbackHistory` for iteration)
- `generate_email` — generate one personalized email for a lead (auto-creates a campaign)
- `generate_email_batch` — generate emails for every lead in a group
- `get_draft_payload` — ready-to-send `{provider,to,subject,body}` payload; chain with Gmail/Outlook MCPs (or any email-sending MCP) to actually send

Lead CRUD (free):
- `list_leads` / `get_lead` / `create_lead` / `update_lead` / `delete_lead`

Campaign CRUD (free):
- `list_campaigns` — all campaigns with stats (lead count, emails sent, reply rate)
- `get_campaign` — single campaign with computed stats
- `get_campaign_stats` — aggregated metrics (totalLeads, emailsGenerated, emailsSent, repliesReceived, replyRate %)

Utility:
- `check_usage` — current token balance, used, limit, remaining

### Quick connect

| Client | Command / path |
|--------|----------------|
| Claude.ai (Web) | Settings → Connectors → Add custom connector → `https://mcp.hypema.app/mcp` |
| Claude Desktop | Settings → Connectors, or edit `claude_desktop_config.json` |
| Claude Code (CLI) | `claude mcp add hypema --transport http https://mcp.hypema.app/mcp` |
| ChatGPT (Dev Mode) | Settings → Apps & Connectors → Add → `https://mcp.hypema.app/mcp` |
| Cursor / VS Code / Windsurf / JetBrains / Zed / Cline / Goose / Gemini ADK | MCP config with `Authorization: Bearer hpm_live_…` |

Full setup for every client: `/docs/mcp.md`.

## REST API — v1

- **Base URL:** `https://hypema.app/api/v1`
- **Auth:** `Authorization: Bearer hpm_live_…` (API key) or Supabase OAuth JWT
- **Envelope:** `{ data, error, meta: { requestId, tokensConsumed } }`
- **Rate limits:** Free 100 pts/min, Pro 500 pts/min. Weights: read=1, write=2, AI single=5, AI heavy=10–15. Headers: `X-RateLimit-Limit / -Remaining / -Reset / -Cost`.
- **Errors:** `VALIDATION_ERROR` (400), `UNAUTHORIZED` (401), `TOKEN_LIMIT_EXCEEDED` (403), `NOT_FOUND` (404), `RATE_LIMITED` (429), `INTERNAL_ERROR` (500).

### Endpoints (20 total)

AI operations (SSE-streaming supported):
- `POST /ai/research-company` — company research by URL
- `POST /ai/generate-leads` — find leads matching given criteria

Email operations:
- `POST /emails/generate-preview` — preview samples without saving (supports `sampleCount`, `feedbackHistory`, `secretSauceVariant`, `effort`)
- `POST /emails/generate` — one email for one lead (auto-creates campaign)
- `POST /emails/generate-batch` — batch across a lead group (supports `perLeadVariants`)
- `GET /emails/:id` — fetch a generated email
- `POST /emails/drafts/payload` — build `{provider,to,subject,body}` and mark lead as `drafted`

Leads:
- `GET /leads` (filter by `status`, `search`, `page`, `per_page`)
- `POST /leads` / `GET /leads/:id` / `PATCH /leads/:id` / `DELETE /leads/:id`

Lead groups:
- `GET /lead-groups` / `POST /lead-groups` / `GET /lead-groups/:id/leads`

Campaigns (auto-created when you generate emails):
- `GET /campaigns` / `GET /campaigns/:id`
- `GET /campaigns/:id/stats` — totalLeads, emailsGenerated, emailsSent, repliesReceived, replyRate
- `GET /campaigns/:id/emails` — every lead + email + send status + replySnippet (filter via `status=sent,replied`)

Usage:
- `GET /usage` — `{ allowed, used, limit, remaining }`

**Parameter enums** (case-sensitive, apply to REST API + MCP):
- `effort`: `max` | `xhigh` | `high` | `medium` | `low` (`xhigh` + `max` Opus 4.7 only). Omit = tenant default.
- `secretSauceVariant`: `reply_rate` | `positive_reply_rate` | `none`. Email endpoints only.
- `perLeadVariants[]`: array of `secretSauceVariant` values (one per lead). `/emails/generate-batch` only.
- Lead `status`: `new` | `generated` | `drafted` | `sent` | `replied` | `bounced`. `GET /leads` filter + `PATCH /leads/:id`.
- Lead group `source`: `manual` | `csv` | `ai`. `POST /lead-groups`.
- Error `code`: `VALIDATION_ERROR` | `UNAUTHORIZED` | `TOKEN_LIMIT_EXCEEDED` | `NOT_FOUND` | `RATE_LIMITED` | `INTERNAL_ERROR`. Response `error.code`.

## Pricing

| Plan | Price (EUR, ex. VAT) | Tokens | Notes |
|------|----------------------|--------|-------|
| Free | €0 forever | 500 one-time credit on signup (no monthly reset) | No credit card. Full feature access. |
| Pro | €49/mo or €441/yr (25% off) | 5,000/mo | Unlimited campaigns, priority support, buy more tokens anytime (never expire). |

Approximate token costs (low Thinking Depth, `none` Sauce): ~2–5 tokens per drafted email · ~10–30 per researched lead · ~5–15 per company-research call · CRUD operations are free. 100 tokens ≈ €1 + VAT.

## Chrome extension

- **Chrome Web Store:** `https://chromewebstore.google.com/detail/hypema-%E2%80%94-precise-email-ou/apnbcdldkcamjajnlmcifgeabhemonpf`
- Creates Gmail drafts from the web app via `postMessage`. Only *writes* drafts — never reads inbox content except the scoped reply-sync scan (which the user triggers) to match thread subjects to sent leads.

## Documentation (markdown mirrors — no JS required)

- `/docs/guide.md` — full web-app guide (10 sections: Getting Started, Chrome Extension, Outreach Workflow, Secret Sauce, Thinking Depth, AI Company Research, API Keys, Billing & Usage, Campaigns & History, FAQ & Troubleshooting)
- `/docs/mcp.md` — MCP integration setup for every supported client + tools reference
- `/docs/api-reference.md` — full REST API reference with cURL examples

Rendered versions (React, JS required): `/docs/guide`, `/docs/mcp`, `/docs/api-reference`.

## Marketing & positioning pages (public)

- `/` — current homepage
- `/v30` — "Precision over volume" manifesto with Seven Laws of Reply
- `/demo/secret-sauce` — interactive UI pattern lab for Sauce-mode selectors

## Compliance, legal, company

- `/privacy` — GDPR privacy policy
- `/terms` — terms of service (includes DPA at `/terms#dpa`)
- `/imprint` — German legal imprint
- `/cookies` — cookie policy
- Operator: **OXO UG (haftungsbeschränkt)** · Seehausen am Staffelsee, Germany
- Hosting: Supabase EU-Frankfurt · Cloudflare Workers (backend + MCP)
- Payments: Polar.sh (Merchant of Record, VAT handled)

## Machine-readable resources

- `/llms.txt` — this file
- `/llms-full.txt` — full single-file reference (comprehensive, for one-shot LLM ingestion)
- `/sitemap.xml` — canonical sitemap
- `/robots.txt` — crawler policy (explicitly allows all major AI bots)
- `/.well-known/ai.txt` — AI usage / training policy
- `/.well-known/security.txt` — security contact (RFC 9116)
- `/humans.txt` — credits

## Contact

- Product & support: **support@hypema.app**
- Business & legal: **service@newstelligent.com**
- Website: **https://hypema.app**
- MCP endpoint: **https://mcp.hypema.app/mcp**

_Last updated: 2026-04-18_