# 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** — 50–100 word body, 1–4 word lowercase subject, 3–5 short lines, peer-to-peer tone, one specific detail, one easy question, no meeting-ask in first email (Lavender / Outbound Squad / Gong 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@newstelligent.com` — 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, `none` Sauce):
- Email generation: ~2–5 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 mode 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 (three copywriting modes)

Proprietary copywriting intelligence 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.

| Mode | Value string | Tokens/email (varies by depth) | Best for |
|------|--------------|-------------------------------|----------|
| **Reply Rate** | `reply_rate` | ~5–30 | Maximize any response (curiosity hooks, open loops, one easy-to-answer question). Awareness, networking, research outreach. |
| **Positive Reply Rate** | `positive_reply_rate` | ~8–51 | Maximize interested replies (outcome-first framing, objection preemption, low-commitment CTA). Sales, partnerships, recruiting. |
| **Cost-efficient** | `none` | ~5–25 | Standard AI copywriting without Sauce. 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):

| Sauce | Low depth | Medium | High | Max |
|-------|-----------|--------|------|-----|
| Cost-efficient | ~1,000 | ~714 | ~333 | ~200 |
| Reply Rate | ~1,000 | ~500 | ~250 | ~166 |
| Positive Reply Rate | ~625 | ~294 | ~104 | ~98 |

---

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

Controls Anthropic's adaptive thinking effort. 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 | Company research time |
|-------|-------|--------------|------------|---------------|----------------------|
| **Low** | `low` | ~4–6 | ~6–7 sec | ~3 min | ~30 sec |
| **Medium** | `medium` | ~4–6 | ~6–9 sec | ~5 min | ~1 min |
| **High** (default) | `high` | ~4–12 | ~7–21 sec | ~10 min | ~3 min |
| **Extra High** | `xhigh` | ~8–18 | ~17–39 sec | ~12 min | ~4 min |
| **Max** | `max` | ~21–52 | ~45 sec–2 min | ~15 min | ~5 min |

`xhigh` and `max` are Opus 4.7 only (earlier models reject those values). All other levels are universal. **Default effort is `high`** for email generation, lead generation, and company research — all three run on Opus 4.7. CSV mapping is the exception: it defaults to `low` and runs on Sonnet 4.6 (lighter operation, deterministic schema-match task). Email numbers measured 2026-04-19 via a 75-run benchmark (5 profile-pairs × 3 sauces × 5 efforts).

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 (15 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, ~5–15 tokens. Research a company by URL. Params: `url` (string, required); `effort` (optional). Returns: `{companyName, description, industry, productName, valueProposition, targetAudience, ceoName, ceoRole}`.
2. `generate_leads` — AI, not read-only, ~10–30 tokens. Web-search for leads matching given criteria. Params: `industry` (required); `roleTitle`, `region`, `count` (1–50, default 5), `companySize`, `excludeGroupIds[]`, `effort` (all optional). Creates a new lead group; returns `{leads[], count, leadGroupId}`.

**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, ~2–10 tokens/preview. Generate 1–10 sample previews without saving. Supports `feedbackHistory[]` for iteration, `secretSauceVariant`, `effort`. Returns `{previews[], count}`.
9. `generate_email` — AI, write, ~2–10 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, ~2–10 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. Omit to use the tenant default. `"none"` explicitly disables the sauce even if the tenant default has one set. |
| `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": "positive_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": "positive_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
- `/v30` — precision manifesto ("Seven Laws of Reply")
- `/demo/secret-sauce` — interactive UI pattern lab

**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:** 1–4 words, lowercase, about the prospect's world (not the product).
- **Body:** 50–100 words, 3–5 short lines, plain text, 5–6th grade reading level.
- **Tone:** informal, peer-to-peer. Never "hope this finds you well", "I hope you're doing well", "I came across…".
- **Opening:** references one specific detail from the research (a hiring post, a product launch, a funding round, a blog post, a Congressional filing — anything recent and public).
- **Proof line:** one concrete outcome from a similar customer (with numbers when possible), 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:** once, by name, no feature list.
- **Self-reference:** max 1 sentence starting with "we" or "our".

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@newstelligent.com |

---

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