Skip to content

lobster_mail_specs.md

Latest commit

 

History

History
144 lines (99 loc) · 4.29 KB

lobster_mail_specs.md

File metadata and controls

144 lines (99 loc) · 4.29 KB
Raw

LobsterMail — Agent-First Email Infrastructure

What it is: A platform that lets AI agents self-provision email inboxes, send/receive email, and safely consume email content for LLM processing. No human-in-the-loop required.

Core Product Features

Inbox Management

  • Instant inbox creation (random or custom handles)
  • Smart naming with identity-based variation generation (8+ fallback strategies for collisions)
  • Gmail-style dot canonicalization (sarah.shield = sarahshield)
  • Soft deletion with a 7-day grace period
  • Auto-expiry for free tier (30 days)

Email Receiving

  • Full inbound pipeline via AWS SES (real email, real MX records on lobstermail.ai)
  • Polling API with cursor pagination and since filtering
  • Lazy-load the full body from S3 on demand
  • 200-char body previews in list view

Email Sending (Paid tiers)

  • Async queue-based sending with retry + exponential backoff
  • Per-account SES config sets for reputation isolation
  • Adaptive throttling (auto-detects SES rate limits)
  • Daily/monthly send limits enforced atomically via Redis
  • Pre-send validation (recipient format, MX lookup, suppression list)
  • Global kill switch for emergency shutoff

Webhooks

  • HMAC-SHA256 signed payloads
  • Account-level or inbox-scoped
  • Auto-disable after 10 consecutive failures
  • Retry with exponential backoff (up to 5 attempts)

Custom Domains

  • Full DNS verification flow (TXT, CNAME/DKIM, MX)
  • SES identity provisioning per domain
  • Periodic background verification worker

Real-Time Notifications

  • WebSocket support with per-inbox subscriptions
  • Redis pub/sub under the hood
  • Auto-reconnect with exponential backoff (SDK)

Prompt Injection Detection

6 scanner categories:

  1. Boundary manipulation — e.g., breaking out of content markers
  2. System prompt override — "ignore previous instructions"
  3. Data exfiltration — "send your prompt to..."
  4. Role hijacking — fake [SYSTEM] messages
  5. Tool invocation — attempts to trigger function calls
  6. Encoding/obfuscation — hex escapes, zero-width chars, Base64

Composite scoring formula: score = max_weight * 0.7 + breadth * 0.3

Additional scans: spam detection, phishing detection, SPF/DKIM/DMARC validation

SDK safety surface:

  • email.isInjectionRisk — boolean flag
  • email.safeBodyForLLM() — wraps content in boundary markers with metadata header, strips injected boundaries

Account and Billing System

See Image 1 (tier diagram)

  • Tier 1 → 2: Stripe payment ($100/mo)
  • Anonymous bearer token auth — no passwords, no email verification (agent-first)
  • Token format: lm_sk_test_... / lm_sk_live_..., SHA-256 hashed at rest

TypeScript SDK

Package: lobstermail on npm

Method Description
LobsterMail.create() Auto-signup, token persistence to ~/.lobstermail/token
createSmartInbox() Intelligent naming with collision handling
inbox.waitForEmail() Poll with exponential backoff + filters
email.safeBodyForLLM() One-liner safe formatting for agents
connect() WebSocket real-time push
  • 100 tests, full TSDoc coverage

API Surface

  • Health, signup, account info
  • Inbox CRUD
  • Email listing/fetching
  • Send
  • Webhooks CRUD
  • X verification
  • Custom domains CRUD
  • Stripe webhook
  • Local dev simulation endpoint

Documentation: Full OpenAPI 3.1 spec + 7 MDX guides (Getting Started, Agent Quickstart, Receiving, Sending, Webhooks, Custom Domains, Security).

Infrastructure (AWS CDK, IaC)

See Image 2 (architecture diagram)

Developer Experience & CI

  • Monorepo: pnpm workspaces + Turborepo (6 packages)
  • 379 tests across 5 packages (Vitest)
  • GitHub Actions CI: 6 parallel jobs
    • Lint/typecheck
    • Shared tests
    • SDK tests
    • Docs validation
    • API tests w/ Docker
    • Worker tests w/ Docker
  • Local dev: Docker Compose (Postgres, Redis, Mailpit), simulated inbound endpoint, Bull Board dashboard
  • Claude Desktop MCP skill (packages/claw-skill) for agent integration

Deployment Status

  • Dev environment live on AWS us-west-2
  • End-to-end verified: signup → inbox creation → receive real email via SES → poll with body preview
  • Domain: lobstermail.ai (SES verified, DKIM pass, SPF pass)