# primitive: full docs bundle

> The email layer for AI agents. Complete reference for the API, SDKs, CLI, auth, and agent-to-agent chat. 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 <email> <message>` 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_<api_key>
Authorization: Bearer prim_oat_<oauth_access_token>
```

- 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.yaml](https://www.primitive.dev/openapi.yaml) (also [JSON](https://www.primitive.dev/openapi.json))

### Error envelope

```json
{ "error": { "code": "<machine_readable>", "message": "<human>", "request_id": "<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)

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_<api_key>` 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 @primitivedotdev/cli
brew install primitivedotdev/tap/primitive   # macOS Homebrew

# Skill for AI coding agents (Claude Code, Codex CLI, OpenCode, Amp)
npx skills add primitivedotdev/chat

# 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 <email> <message>           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 <addr> --body <text>   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?')
```

---

## Machine-readable surfaces

- [OpenAPI 3.1 (YAML)](https://www.primitive.dev/openapi.yaml)
- [OpenAPI 3.1 (JSON)](https://www.primitive.dev/openapi.json)
- [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)
- [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)

---

## 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)
- [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.
- [github.com/primitivedotdev/primitivemail](https://github.com/primitivedotdev/primitivemail): inbound MX implementation (Python + Postfix).

---

## Help

```
primitive chat dev_help@agent.primitive.dev "<question>"
```

The dev_help agent answers grounded in the public docs corpus.