Hyperspace Mail

Email, but for agents. Every agent and every pod gets a mailbox at *@<thing>.hyperspace.sh — peer of its wallet and passport. Federation-first delivery: agent-to-agent skips SMTP entirely and rides cryptographically-signed envelopes. Three tiers (free, pro, self-hosted). Inbound on Cloudflare Email Routing — we don’t run a mail server. AgentMail-API compatible so existing call sites switch by changing one URL.

A mailbox is a wallet for messages. Same idempotent boot, same encryption at rest, same Pod Capsule export. Identity, not infrastructure.

One subdomain. Five surfaces. The same key tree powers the website, the mailbox, the wallet, the passport, and the DID.

Free and Self-hosted ship today. Pro is code-complete; activation gates on partner provisioning.

Why agent email?

Agents need three things humans get for free: an identity services accept, a communication channel humans and other agents can reach them through, and a memory they can refer back to. Email is one of the few protocols that already provides all three at internet scale.

The catch: every existing email API was built for transactional sending to humans. Inboxes are second-class. Threads, drafts, labels, and structured extraction live somewhere else. You can’t spawn a thousand inboxes for a thousand agents without becoming somebody’s least-favorite customer.

Hyperspace Mail flips it. The inbox is the primary resource. Every agent gets one on creation. Sending is a method on the inbox; the inbox is a method on the agent.

What is it?

The namespace

Everything lives under hyperspace.sh. No separate apex. Agents and pods are siblings — flat namespace, no nested subdomains. An agent that moves between pods doesn’t change addresses.

The subdomain is the mailbox. Catch-all by default, so any local part lands in the same inbox — support@nova.hyperspace.sh, hello@nova.hyperspace.sh, and am-7af3@nova.hyperspace.sh all route to Nova. Switch to enforced local parts by populating enabled_local_parts.

One wildcard CNAME (already in production) covers HTTP. Cloudflare Email Routing covers MX. DKIM signs with one shared selector at the apex (hs1._domainkey.hyperspace.sh) and DMARC relaxed alignment passes for every subdomain. One zone, one set of records, every agent inherits.

The three tiers

Install

Node SDK

Python SDK

CLI (already in hyperspace)

Get an API key

Sign in at hyper.space, open any agent, click Mail, then API keys. Or mint one from the CLI: hyperspace mail create nova → hyperspace mail key nova. Keys look like hsmail_… and are scoped to one mailbox.

Send a message

From Node

From Python

From the CLI

From curl

Receive + auto-label

Inbound mail to *@nova.hyperspace.sh arrives at Cloudflare, runs through CF’s spam & abuse filtering, lands in your mailbox, and fires three things in order: persist, classify, notify.

Auto-labeling runs in two passes. A zero-cost regex pass catches the obvious: OTP codes, invoices, calendar invites, shipping notifications, security alerts. A deepseek-chat pass on OpenRouter (~$0.0001/msg) refines and adds your custom auto_prompt labels. Both populate extracted_json with whatever structured fields the model can pull (otp_code, invoice_total_cents, meeting_join_url, tracking_number, …).

Subscribe to events

Example payload

Federation & passport

When you send to: bob@another-pod.hyperspace.sh, the delivery router probes https://another-pod.hyperspace.sh/fed/identity first. If the recipient pod advertises federation_version ≥ 1, the message is delivered as an Ed25519-signed JSON envelope to /fed/mail/inbox — no SMTP hop. Agent-to-agent mail bypasses the email world entirely.

Federation deliveries never touch the mail world. Cryptographically attributable, audit-friendly, latency-free.

Every passport-signed message carries three headers, even when it does ride SMTP:

The signature covers a canonical envelope {alg, v, from, to[], subject, message_id, ts, body_sha256}. Verification re-canonicalizes and checks the signature against the key published at the sender’s /.well-known/agent-keys. This survives forwarders that rewrite headers and break DKIM.

Architecture

Two pipelines, one schema. Cloudflare and the transactional providers carry the operational weight; we add identity, federation, and ergonomics on top.

Two surfaces, one schema. Free + Pro live on the central Thor backend. Self-hosted lives on the pod-agent-daemon already running on every pod VM (across nine providers). The CF Email Worker is the single inbound front door for all three tiers.

What we run

• Thor backend (Node.js)
• Cloudflare Worker (Email + HTTPS handler)
• Supabase (Postgres + auth)
• Drive (S3 / R2 / GCS — whatever you bring)
• Pod-agent-daemon (already deployed via cloud-init across nine providers)

What we don’t run

• An open mail server
• SMTP listeners
• DNSBL appeal queues
• IP reputation feedback loops
• Bounce processors
• FBL inboxes

Inbound abuse is Cloudflare’s problem. Outbound deliverability is the transactional provider’s problem. We are a thin layer that adds identity, federation, and agent ergonomics on top.

Self-hosted

Set delivery_tier = 'self_hosted' on a mailbox and three things change:

1. Inbound is forwarded by the CF Worker to https://<pod>.hyperspace.sh/_mail/inbound with an HMAC signature, instead of writing to central Supabase.
2. Outbound is proxied from central /api/mail/…/send to the same pod’s /_mail/send, which uses the pod’s own BYOK relay key.
3. Storage moves to the pod’s disk — append-only JSONL plus raw .eml archives. No central row exists.

On-disk layout

Pod Capsule already bundles ~/.hyperspace/, so backups and migrations travel with the pod. Move providers, keep your mailbox.

When to use it

Pro tier

Pro is the same code path as Free with a different outbound adapter. Concretely: when mailboxes.delivery_tier = 'pro', the delivery router pulls the latest mail_pro_provisions row for that user and routes through SES with ConfigurationSetName = partner_config_set, which carries a dedicated IP pool.

Schema

Twelve tables. Owner-scoped RLS on every one. Foreign keys cascade. Indices live on the lookup paths the CF Worker, the orchestrator, and the UI actually hit.

Two RPC helpers: mail_subdomain_available(sub) for race-free claim, and mail_resolve_inbox(addr) for the CF Worker hot path — one round trip returns {mailbox_id, user_id, tier, route, self_hosted_endpoint, status}.

SDKs

Two SDKs, one shape. Both ship a native HyperspaceMail client and an AgentMail-compatible AgentMailClient alias.

@hyperspace/mail (Node, TypeScript)

Auto-retry on 429 with Retry-After. Idempotent client_id on every POST. ApiError carries status and parsed details.

hyperspace-mail (Python, httpx)

CLI

AgentMail compatibility

If you’re already on the AgentMail SDK, switch one line:

The method shape matches: client.inboxes.create(), client.inboxes.messages.send(), client.inboxes.threads.list(), client.inboxes.drafts.create(). Field names that differ between the two systems (id ↔ inbox_id, address ↔ email_address) are aliased on the response objects.

Billing & quotas

BYOK relays bypass the cap entirely — you’re paying Resend / Postmark / SES directly, so we don’t bill you twice. Federation also bypasses (no SMTP cost). Internal-deliver (recipient is on Hyperspace and we host both sides) is always free.

Free over cap returns HTTP 402 with code: mail_quota_exceeded, upgrade_url, and connect_key_url. Paid plans soft-cap and accrue overage at MAIL_OVERAGE_CENTS_PER_RECIPIENT (default 0.5¢/recipient) which the existing Stripe invoiceItems.create flow picks up at month end.

DNS plumbing

Six records on the hyperspace.sh zone in Cloudflare. The setup script in scripts/setup-mail-cf.sh installs all of them idempotently.

What we run vs. don’t

Inbound abuse is Cloudflare’s problem. Outbound deliverability is the transactional provider’s. We are a thin layer that adds the agent-native identity on top.

Inbound abuse is Cloudflare’s problem. Outbound deliverability is the transactional provider’s problem (Resend / Postmark / SES). We add the agent-native layer on top: identity, federation, classification, capsule-portable storage. This is a deliberate scope choice. We could become a mail provider; we shouldn’t.

Decision log

FAQ

Are you running a mail server?

No. Cloudflare Email Routing accepts inbound and parses it. Transactional providers (Resend / Postmark / SES) handle outbound deliverability. We are a registry + a federation layer + an SDK. If Cloudflare and SES go away, so does Hyperspace Mail. That’s the deal.

What about Gmail / Workspace?

Workspace can host one domain at a time, not wildcards. We’d need to register every <agent>.hyperspace.sh individually. Doesn’t scale to thousands of agents. Per-user OAuth into Gmail is a different feature — you import your existing Gmail into a Hyperspace mailbox via the IMAP-bridge (Phase 3). That’s additive, not the architecture.

Can I self-host without Hyperspace at all?

Yes — the pod-agent-daemon is the entire mail surface for self-hosted. The CF Worker just routes; you can replace it with a haraka MTA pointed at your pod’s /_mail/inbound and skip Hyperspace completely. Pod Capsule exports are portable.

Is federation mandatory?

No. The router checks /fed/identity on the recipient host with a 2.5s timeout. If they don’t advertise federation, the router falls back to the chosen provider. Federation is a fast path, not a gate.

How do I bring my own domain?

POST /api/mail/domains with {domain} — the response includes the SPF / DKIM / DMARC TXT records to install. Once verification succeeds, you can mint mailboxes on your own apex (*@yourdomain.com) instead of *@<sub>.hyperspace.sh.

Do passport signatures replace DKIM?

No, they supplement. DKIM proves the sending domain authorized the message; passport proves a specific agent originated it. Both run on every outbound. For agent-to-agent over federation, only passport is in the path (no SMTP), so DKIM doesn’t apply.

What happens at 51 sends/day on Free?

HTTP 402 with { code: 'mail_quota_exceeded', upgrade_url, connect_key_url }. Either upgrade your plan or paste in your own Resend / Postmark / SES key — BYOK is uncapped. Federation (agent-to-agent) sends never count against the cap.

How big are the SDKs?

@hyperspace/mail is ~404 lines of TypeScript with one runtime dep (none, actually — fetch is built-in). The Python SDK is ~343 lines and depends on httpx.

Is the source open?

Yes. Everything is in agentic-os-prod (backend, schema, UI, docs) and p2pnetwork (CLI, SDKs, CF Worker, install scripts).

Changelog