# primitive: full docs bundle > Primitive is email infrastructure for AI agents. Complete reference for the API, SDKs, CLI, auth, 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. Two 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. The `primitive chat ` CLI verb wires both 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://www.primitive.dev/app/settings/api-keys](https://www.primitive.dev/app/settings/api-keys) - OAuth AS metadata: [https://www.primitive.dev/.well-known/oauth-authorization-server](https://www.primitive.dev/.well-known/oauth-authorization-server) (RFC 8414) - Protected resource metadata: [https://www.primitive.dev/.well-known/oauth-protected-resource](https://www.primitive.dev/.well-known/oauth-protected-resource) (RFC 9728) - Full auth walkthrough: [https://www.primitive.dev/auth.md](https://www.primitive.dev/auth.md) - Agent signup (email-only verification): `POST https://api.primitive.dev/v1/agent/signup/start` (see [auth.md](https://www.primitive.dev/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}/deploy` - **Agent signup**: `POST /agent/signup/start`, `POST /agent/signup/verify` Full OpenAPI 3.1 spec: [https://www.primitive.dev/openapi.json](https://www.primitive.dev/openapi.json) (also [YAML](https://www.primitive.dev/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://www.primitive.dev/docs/errors](https://www.primitive.dev/docs/errors); versioning + deprecation policy at [https://www.primitive.dev/docs/versioning](https://www.primitive.dev/docs/versioning). --- ## MCP server Primitive hosts a Model Context Protocol server at [https://www.primitive.dev/mcp](https://www.primitive.dev/mcp) (streamable-http transport, stateless). - Discovery: [https://www.primitive.dev/.well-known/mcp](https://www.primitive.dev/.well-known/mcp) - Server card: [https://www.primitive.dev/.well-known/mcp/server-card.json](https://www.primitive.dev/.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), [mcp.so](https://mcp.so/server/primitive-email/primitivedotdev) - 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. Tools (with behavioral annotations per the MCP spec): - [`getAccount`](https://www.primitive.dev/.well-known/mcp/server-card.json), [`getInboxStatus`](https://www.primitive.dev/.well-known/mcp/server-card.json), [`listEmails`](https://www.primitive.dev/.well-known/mcp/server-card.json), [`searchEmails`](https://www.primitive.dev/.well-known/mcp/server-card.json), [`getEmail`](https://www.primitive.dev/.well-known/mcp/server-card.json): all `readOnlyHint=true`, `idempotentHint=true`. - [`replyToEmail`](https://www.primitive.dev/.well-known/mcp/server-card.json), [`sendEmail`](https://www.primitive.dev/.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://www.primitive.dev/.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 primitive # 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 deploy Deploy an inbound email handler 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: ```ts export default async function handler(email) { // email.from, email.subject, email.body, email.reply(text) await email.reply("Got it, processing now.") } ``` Deploy with: `primitive functions deploy` --- ## 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://www.primitive.dev/docs/collecting-payments](https://www.primitive.dev/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://www.primitive.dev/docs/paying-x402-over-email](https://www.primitive.dev/docs/paying-x402-over-email). - **Protocol, pinned-payer trust model, and wire format:** [https://www.primitive.dev/docs/x402-over-email](https://www.primitive.dev/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://www.primitive.dev/openapi.json) - [OpenAPI 3.1 (YAML)](https://www.primitive.dev/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://www.primitive.dev/mcp) (Streamable HTTP) - [MCP discovery](https://www.primitive.dev/.well-known/mcp) and [server card](https://www.primitive.dev/.well-known/mcp/server-card.json) - [Agent card (A2A / Google)](https://www.primitive.dev/.well-known/agent-card.json) - [Agent discovery](https://www.primitive.dev/.well-known/agent.json) - [API catalog (RFC 9727)](https://www.primitive.dev/.well-known/api-catalog) - [OAuth AS metadata (RFC 8414)](https://www.primitive.dev/.well-known/oauth-authorization-server) - [OAuth protected resource (RFC 9728)](https://www.primitive.dev/.well-known/oauth-protected-resource) - Agentic Commerce Protocol (ACP): checkout sessions at `https://www.primitive.dev/checkout_sessions` (mirror of `https://api.primitive.dev/checkout_sessions`) and delegated payment at `https://www.primitive.dev/agentic_commerce/delegate_payment` — both respond to a CORS preflight - [Agents.md](https://www.primitive.dev/agents.md) (instructions for product agents) - [Agent skills directory](https://www.primitive.dev/.well-known/agent-skills) - [Auth walkthrough](https://www.primitive.dev/auth.md) - [Short orientation](https://www.primitive.dev/llms.txt) - [API-only llms.txt](https://www.primitive.dev/api/llms.txt) - [Developer llms.txt](https://www.primitive.dev/developers/llms.txt) --- ## Pricing Inlined here so agents can answer "what does it cost?" without a follow-up fetch to [https://www.primitive.dev/pricing.md](https://www.primitive.dev/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, 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, 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://www.primitive.dev/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://www.primitive.dev/docs/quickstart) - [REST API](https://www.primitive.dev/docs/api) - [Errors](https://www.primitive.dev/docs/errors) (typed envelope + full code table) - [Versioning](https://www.primitive.dev/docs/versioning) (v1 contract scope, sunset policy) - [Webhooks](https://www.primitive.dev/docs/webhook-payload) - [Collecting payments (x402, payee)](https://www.primitive.dev/docs/collecting-payments) - [Pay an x402 request over email (payer)](https://www.primitive.dev/docs/paying-x402-over-email) - [x402 over email (protocol)](https://www.primitive.dev/docs/x402-over-email) - [Signature verification](https://www.primitive.dev/docs/signature-verification) - [SDKs](https://www.primitive.dev/docs/sdks) - [CLI](https://www.primitive.dev/docs/cli) - [FAQ](https://www.primitive.dev/docs/faq) - [Status](https://www.primitive.dev/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.