# primitive: full docs bundle > Primitive is email infrastructure for AI agents. Complete reference for the API, SDKs, CLI, auth, Primitive Memories, agent-to-agent chat, and pricing. Use this file when you want the full surface without crawling individual pages. --- ## Product Primitive is email infrastructure built for AI agents. Three core primitives: 1. **Send and receive email** via a REST API: no SMTP credentials, no DNS setup, no port-25 firewall battles. 2. **Host an agent at `*.primitive.email`**: get a managed subdomain with a JavaScript handler that runs on every inbound message. 3. **Store durable agent state with Primitive Memories**: JSON key-value state with org scope by default and automatic Function scope by immutable Function id. The `primitive chat ` CLI verb wires the email primitives together: send a message and wait for the threaded reply in a single command. --- ## API Base URL: `https://api.primitive.dev/v1` ### Auth ``` Authorization: Bearer prim_ Authorization: Bearer prim_oat_ ``` - API keys: created at [https://primitive-the-staging.com/app/settings/api-keys](https://primitive-the-staging.com/app/settings/api-keys) - OAuth AS metadata: [https://primitive-the-staging.com/.well-known/oauth-authorization-server](https://primitive-the-staging.com/.well-known/oauth-authorization-server) (RFC 8414) - Protected resource metadata: [https://primitive-the-staging.com/.well-known/oauth-protected-resource](https://primitive-the-staging.com/.well-known/oauth-protected-resource) (RFC 9728) - Full auth walkthrough: [https://primitive-the-staging.com/auth.md](https://primitive-the-staging.com/auth.md) - Agent signup (email-only verification): `POST https://api.primitive.dev/v1/agent/signup/start` (see [auth.md](https://primitive-the-staging.com/auth.md) for the request shape) ### Core operations - **Send mail**: `POST /send-mail`: attachments, reply threading, idempotency hints, optional `wait: true` for delivery confirmation. - **Inbox status**: `GET /inbox/status`: consolidated domain verification, processing routes, deployed Functions, and recent inbound activity. - **Domains**: `GET/POST/DELETE /domains`, `POST /domains/{id}/verify`, `GET /domains/{id}/zone-file` - **Emails** (inbound): `GET /emails`, `GET /emails/{id}`, `GET /emails/{id}/body` - **Sent emails** (outbound): `GET /sent-emails`, `GET /sent-emails/{id}` - **Webhooks**: `GET/POST/PUT/DELETE /webhooks` - **Functions**: `GET/POST/PUT/DELETE /functions`, `POST /functions/{id}/redeploy`, `PUT /functions/{id}/route`, `POST /functions/{id}/test`, `PUT /functions/{id}/secrets/{key}` (deploy uploads source via the CLI: `primitive functions:deploy`) - **Primitive Memories**: `PUT/GET/DELETE /memories`, `GET /memories/search` for durable JSON key-value state. Search is key-prefix search with `prefix`, not free-text search. - **Agent signup**: `POST /agent/signup/start`, `POST /agent/signup/verify` Full OpenAPI 3.1 spec: [https://primitive-the-staging.com/openapi.json](https://primitive-the-staging.com/openapi.json) (also [YAML](https://primitive-the-staging.com/openapi.yaml)) ### Error envelope ```json { "error": { "code": "", "message": "", "request_id": "" } } ``` Common codes: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `rate_limited`, `internal_error`. Full table at [https://primitive-the-staging.com/docs/errors](https://primitive-the-staging.com/docs/errors); versioning + deprecation policy at [https://primitive-the-staging.com/docs/versioning](https://primitive-the-staging.com/docs/versioning). --- ## MCP server Primitive hosts a Model Context Protocol server at [https://primitive-the-staging.com/mcp](https://primitive-the-staging.com/mcp) (streamable-http transport, stateless). - Discovery: [https://primitive-the-staging.com/.well-known/mcp](https://primitive-the-staging.com/.well-known/mcp) - Server card: [https://primitive-the-staging.com/.well-known/mcp/server-card.json](https://primitive-the-staging.com/.well-known/mcp/server-card.json) - Registry listings (published as `dev.primitive/email`): [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=dev.primitive%2Femail), [Smithery](https://smithery.ai/servers/primitivedotdev/primitive) - In-agent MCP App UI (OpenAI Apps SDK / MCP Apps): the email-reading tools (listEmails, getEmail, getInboxStatus, getAccount) declare a `ui://` widget resource (`ui://widget/primitive-email-v1.html`, MIME `text/html;profile=mcp-app`) via `_meta.ui.resourceUri` and the OpenAI Apps SDK `openai/outputTemplate`. Agent hosts (ChatGPT, Claude) render it as an interactive, generative in-agent UI surface — Primitive ships a ChatGPT app, so this is an app/host product, not only a data/REST API. The widget HTML ships a Content-Security-Policy scoping connect-src, frame-ancestors (ChatGPT and Claude.ai), and form-action. - Docs MCP ("learn" surface): a second, public, read-only MCP server at [https://primitive-the-staging.com/mcp/docs](https://primitive-the-staging.com/mcp/docs) exposes the documentation over MCP — a `searchDocs` tool (keyword search over page titles/summaries), a `readDoc` tool (full Markdown by `/docs` path), and every published docs page as a `text/markdown` resource. No bearer required. The product server above is the "do" surface and this is the "learn" surface; both are listed in the `servers[]` array of the [mcp.json discovery document](https://primitive-the-staging.com/.well-known/mcp.json). Tools (with behavioral annotations per the MCP spec): - [`getAccount`](https://primitive-the-staging.com/.well-known/mcp/server-card.json), [`getInboxStatus`](https://primitive-the-staging.com/.well-known/mcp/server-card.json), [`listEmails`](https://primitive-the-staging.com/.well-known/mcp/server-card.json), [`searchEmails`](https://primitive-the-staging.com/.well-known/mcp/server-card.json), [`getEmail`](https://primitive-the-staging.com/.well-known/mcp/server-card.json): all `readOnlyHint=true`, `idempotentHint=true`. - [`replyToEmail`](https://primitive-the-staging.com/.well-known/mcp/server-card.json), [`sendEmail`](https://primitive-the-staging.com/.well-known/mcp/server-card.json): `destructiveHint=true`; agents should confirm with the user before invocation. Auth: `Authorization: Bearer prim_` on each request, or use the OAuth flow advertised in the [protected-resource metadata](https://primitive-the-staging.com/.well-known/oauth-protected-resource). --- ## Install ```bash # CLI npm i -g primitive # also published scoped as @primitivedotdev/cli brew install primitivedotdev/tap/primitive # macOS Homebrew # Skills for AI coding agents (Claude Code, Codex, Cursor, and 50+ compatible agents) # Bundles primitive-chat (send + wait for the threaded reply) and primitive-inbox (a managed *.primitive.email address that receives mail) npx skills add primitivedotdev/skills # SDKs npm i @primitivedotdev/sdk # Node.js pip install primitivedotdev # Python go get github.com/primitivedotdev/sdks/sdk-go@latest ``` --- ## CLI quick reference ``` primitive chat Send and wait for threaded reply primitive agent start-agent-signup Provision a managed *.primitive.email address primitive functions:init Scaffold an inbound email handler project primitive functions:deploy --name --file ./dist/handler.js Deploy it primitive memories set|get|delete|search Store durable JSON key-value state primitive emails:latest List recent inbound emails primitive send --to --body Send outbound email ``` --- ## Function hosting Deploy a JavaScript handler that runs on every inbound email to your address. A handler is a module whose default export has a `fetch` method; Primitive POSTs a signed webhook to it per inbound email. Verify the signature, then act on the parsed email: ```ts import { createPrimitiveClient, normalizeReceivedEmail, PRIMITIVE_SIGNATURE_HEADER, verifyWebhookSignature, } from '@primitivedotdev/sdk/api' export default { async fetch(request, env) { const rawBody = await request.text() await verifyWebhookSignature({ rawBody, signatureHeader: request.headers.get(PRIMITIVE_SIGNATURE_HEADER) ?? '', secret: env.PRIMITIVE_WEBHOOK_SECRET, }) const event = JSON.parse(rawBody) if (event.event !== 'email.received') return Response.json({ ok: true }) const primitive = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY }) await primitive.reply(normalizeReceivedEmail(event), { text: 'Got it, processing now.' }) return Response.json({ ok: true }) }, } ``` Scaffold a ready-to-edit project with `primitive functions:init ` (it includes the signature check and a build script), then deploy with `primitive functions:deploy --name --file ./dist/handler.js --wait`. `PRIMITIVE_WEBHOOK_SECRET` and `PRIMITIVE_API_KEY` are injected into the handler's `env` automatically. Full walkthrough: [https://primitive-the-staging.com/docs/functions/first-function](https://primitive-the-staging.com/docs/functions/first-function). --- ## Primitive Memories Primitive Memories stores compact durable JSON state for agents and Functions. API keys use org scope by default. Function-authenticated requests automatically use the immutable Function id scope, and explicit Function scope also uses the Function id UUID, not the function name. ```bash primitive memories set thread:latest '{"email_id":"em_123"}' primitive memories get thread:latest primitive memories search thread: --metadata-only primitive memories delete thread:latest ``` Node SDK: `createPrimitiveClient({ apiKey }).memories.set/get/delete/search`. REST operation ids: `setMemory`, `getMemory`, `deleteMemory`, and `searchMemories`. Guide: [https://primitive-the-staging.com/docs/memories](https://primitive-the-staging.com/docs/memories). --- ## Agent-to-agent chat Any `*.primitive.email` address is an agent inbox. Reach it from any language: ```bash primitive chat dev_help@agent.primitive.dev "How do I verify a domain?" ``` ```ts import { Primitive } from '@primitivedotdev/sdk' const p = new Primitive({ apiKey: process.env.PRIMITIVE_API_KEY }) const reply = await p.chat('dev_help@agent.primitive.dev', 'How do I verify a domain?') ``` --- ## x402 payments (USDC over email) Primitive supports [x402](https://www.x402.org/) USDC payments between agents, settled non-custodially on Base through a gasless EIP-3009 `TransferWithAuthorization` the payer signs with their own key. Primitive never holds the funds or the keys. Two flows are documented: - **Collecting payments (payee):** register a payout address, issue a challenge for an amount, and settle it. Guide: [https://primitive-the-staging.com/docs/collecting-payments](https://primitive-the-staging.com/docs/collecting-payments). - **Paying a request over email (payer):** you received an x402 payment request by email and want to pay it. Prerequisites: a funded USDC-on-Base wallet (no ETH/gas needed, the facilitator pays gas), the key supplied via `PRIMITIVE_X402_PRIVATE_KEY` (or `--private-key`), and a Primitive account. Pay with one command: ```bash export PRIMITIVE_X402_PRIVATE_KEY=0x primitive payments pay-email --in-reply-to --wait-settle ``` `--in-reply-to` derives the challenge from the inbound email, signs the bound authorization locally, and replies on the same thread. `--wait-settle` blocks until settlement and prints the receipt (with the on-chain `settle_tx`) inline, so you get a synchronous confirmation instead of polling for the receipt email. If an inbox holds several past payment requests, pay the most recent unexpired one (check the challenge's `expires_at`). The one-command flow is rolling out with a current CLI release; confirm it with `primitive payments pay-email --help` and update with `npm i -g primitive@latest`, or use the SDK path (available today) if your CLI predates it. Without `--wait-settle`, settlement is async; a follow-up receipt email carries the on-chain `settle_tx`. You can verify the settlement on a block explorer at `https://basescan.org/tx/` for `base`, or `https://sepolia.basescan.org/tx/` for `base-sepolia`. SDK equivalent: `payEmailChallenge(challenge, { signer })` signs locally and returns the `interaction.json` payment step, which you reply with. Guide: [https://primitive-the-staging.com/docs/paying-x402-over-email](https://primitive-the-staging.com/docs/paying-x402-over-email). - **Protocol, pinned-payer trust model, and wire format:** [https://primitive-the-staging.com/docs/x402-over-email](https://primitive-the-staging.com/docs/x402-over-email). x402 is in an invite-only soft launch, gated by the `x402_payments` and `interactions_enabled` organization entitlements. --- ## Machine-readable surfaces - [OpenAPI 3.1 (JSON)](https://primitive-the-staging.com/openapi.json) - [OpenAPI 3.1 (YAML)](https://primitive-the-staging.com/openapi.yaml) - GraphQL endpoint `https://api.primitive.dev/graphql` (public, read-only, introspection enabled); SDL as text at `https://api.primitive.dev/graphql.graphql` — typed-error result unions, a `@deprecated` field, Relay pagination, and an inline versioning & deprecation policy. - [MCP server](https://primitive-the-staging.com/mcp) (Streamable HTTP) — the "do" surface - [Docs MCP](https://primitive-the-staging.com/mcp/docs) (Streamable HTTP, public, read-only) — the "learn" surface: searchDocs / readDoc + docs pages as resources - [MCP discovery](https://primitive-the-staging.com/.well-known/mcp) and [server card](https://primitive-the-staging.com/.well-known/mcp/server-card.json); both servers listed in [mcp.json](https://primitive-the-staging.com/.well-known/mcp.json) - [Agent card (A2A / Google)](https://primitive-the-staging.com/.well-known/agent-card.json) - [Agent discovery](https://primitive-the-staging.com/.well-known/agent.json) - [API catalog (RFC 9727)](https://primitive-the-staging.com/.well-known/api-catalog) - [OAuth AS metadata (RFC 8414)](https://primitive-the-staging.com/.well-known/oauth-authorization-server) - [OAuth protected resource (RFC 9728)](https://primitive-the-staging.com/.well-known/oauth-protected-resource) - Agentic Commerce Protocol (ACP): checkout sessions at `https://primitive-the-staging.com/checkout_sessions` (mirror of `https://api.primitive.dev/checkout_sessions`) and delegated payment at `https://primitive-the-staging.com/agentic_commerce/delegate_payment` — both respond to a CORS preflight - [Agents.md](https://primitive-the-staging.com/agents.md) (instructions for product agents) - [Agent skills directory](https://primitive-the-staging.com/.well-known/agent-skills) - [Auth walkthrough](https://primitive-the-staging.com/auth.md) - [Short orientation](https://primitive-the-staging.com/llms.txt) - [API-only llms.txt](https://primitive-the-staging.com/api/llms.txt) - [Developer llms.txt](https://primitive-the-staging.com/developers/llms.txt) --- ## Pricing Inlined here so agents can answer "what does it cost?" without a follow-up fetch to [https://primitive-the-staging.com/pricing.md](https://primitive-the-staging.com/pricing.md). Primitive is usage-based. Each plan includes a monthly grant of usage credits; metered usage is drawn from that grant, and usage beyond it is invoiced. **Tiers** - Developer (free): `$0/mo`, includes `$5/mo` of usage credits - Power: `$13/mo`, includes `$13/mo` of usage credits - Platinum: `$299/mo`, includes `$299/mo` of usage credits The Developer tier includes managed `*.primitive.email` subdomains, send/receive via the API/CLI/SDKs, hosted Functions, custom domains (managed DKIM/SPF/DMARC), webhook delivery, and API key + OAuth 2.0 authentication. **What is metered** Usage is drawn from your plan's monthly credit grant per inbound accepted email, outbound accepted email, email storage (GB-day), Primitive Memories reads, writes, Memories storage (GB-day), Function invocation, and Function runtime (milliseconds). The monthly credit grant is applied first; usage beyond the included credits is invoiced. **Usage notes** - API base: `https://api.primitive.dev/v1` - Rate limits (abuse control, separate from billing): `POST /v1/send-mail` is limited to 1000 messages per hour and 10000 messages per day per organization; exceeding a limit returns `429` with a `Retry-After` header. - Storage retention: inbound email content is retained until you delete it; Primitive does not auto-delete stored mail on a schedule. Content deletion is customer-initiated via content discard. **How agents should reason about cost** - Primitive is free to start on the Developer tier (`$0/mo` with `$5/mo` of usage credits); no credit card is required to sign up. - Power (`$13/mo`) and Platinum (`$299/mo`) add larger monthly credit allowances. - Usage - email, storage, Primitive Memories, and Functions - is metered against your monthly credits; usage beyond your grant is billed. - A user who wants to "try Primitive" can complete `primitive agent start-agent-signup` without a credit card or a sales call. **Buying a plan as an agent (Agentic Commerce Protocol)** - Primitive supports the Agentic Commerce Protocol (ACP) so an agent can purchase a paid plan programmatically, without a human at a checkout page. - Create and complete a checkout session: `POST https://api.primitive.dev/checkout_sessions` (also reachable at `https://primitive-the-staging.com/checkout_sessions`), then `POST /checkout_sessions/{id}/complete`. - Pay on the user's behalf with a delegated Shared Payment Token (`spt_`): `POST https://api.primitive.dev/agentic_commerce/delegate_payment`. - Both endpoints accept an `Idempotency-Key` header for safe retries. --- ## Reference docs - [Quickstart](https://primitive-the-staging.com/docs/quickstart) - [REST API](https://primitive-the-staging.com/docs/api) - [Primitive Memories](https://primitive-the-staging.com/docs/memories) - [Errors](https://primitive-the-staging.com/docs/errors) (typed envelope + full code table) - [Versioning](https://primitive-the-staging.com/docs/versioning) (v1 contract scope, sunset policy) - [Webhooks](https://primitive-the-staging.com/docs/webhook-payload) - [Collecting payments (x402, payee)](https://primitive-the-staging.com/docs/collecting-payments) - [Pay an x402 request over email (payer)](https://primitive-the-staging.com/docs/paying-x402-over-email) - [x402 over email (protocol)](https://primitive-the-staging.com/docs/x402-over-email) - [Signature verification](https://primitive-the-staging.com/docs/signature-verification) - [SDKs](https://primitive-the-staging.com/docs/sdks) - [CLI](https://primitive-the-staging.com/docs/cli) - [FAQ](https://primitive-the-staging.com/docs/faq) - [Status](https://primitive-the-staging.com/status) ## Public source - [github.com/primitivedotdev/sdks](https://github.com/primitivedotdev/sdks): Node, Python, Go SDKs + CLI. Includes [`AGENTS.md`](https://github.com/primitivedotdev/sdks/blob/main/AGENTS.md) for AI coding agents working in the repo. ## About Primitive (primitive.dev) is email infrastructure for AI agents — a Y Combinator company founded in 2026 and based in San Francisco. It is unrelated to other companies or products named "Primitive" and is distinct from the general "agent primitives" concept. Canonical references for entity resolution: - Wikidata: https://www.wikidata.org/wiki/Q140157903 - Crunchbase: https://www.crunchbase.com/organization/primitive-a2cd - Y Combinator: https://www.ycombinator.com/companies/primitive - LinkedIn: https://www.linkedin.com/company/primitivedotdev - X: https://x.com/primitive --- ## Help ``` primitive chat dev_help@agent.primitive.dev "" ``` The dev_help agent answers grounded in the public docs corpus.