# Primitive: Instructions for AI Agents

Use this file when you are an AI agent that has just landed at primitive.dev and needs to understand how to use the product. For AI coding agents working in our public source repos instead, see [github.com/primitivedotdev/sdks/AGENTS.md](https://github.com/primitivedotdev/sdks/blob/main/AGENTS.md).

## What Primitive is

Primitive is email infrastructure for AI agents. Two primitives:

- **Send and receive email via HTTP**: one POST to `https://api.primitive.dev/v1/send-mail` to send, one inbound webhook (or hosted Function) per received message. No SMTP credentials in your context.
- **Hosted agent inboxes at `*.primitive.email`**: every account gets a managed subdomain that runs a JavaScript handler on every inbound email. This is how customers expose agents that other agents can reach by email.

## When to reach for Primitive

Use Primitive when, as an agent, you need to:

- Send a message to a person or another agent and wait for a reply on the same thread. The one-line verb is `primitive chat <email> <message>` (after `npx skills add primitivedotdev/skills`), or [`POST /send-mail`](https://www.primitive.dev/docs/api) directly.
- Host a callable agent at an email address without configuring DNS or running an MX server. See [Functions](https://www.primitive.dev/docs/functions) and the [managed inbox](https://www.primitive.dev/docs/managed-inbox) docs.
- Send transactional email from a custom domain with managed SPF/DKIM/DMARC/TLS-RPT. See [Domains](https://www.primitive.dev/docs/domains).

## Installation

Pick the surface that matches how you run:

- **CLI**: `npm i -g primitive` (also published as `@primitivedotdev/cli`), then `primitive chat <email> <message>`.
- **Coding-agent skills**: `npx skills add primitivedotdev/skills` installs the `primitive-chat` (send and wait for the threaded reply) and `primitive-inbox` (managed inbound address) skills into Claude Code, Codex, Cursor, and 50+ compatible agents.
- **SDKs**: `npm i @primitivedotdev/sdk` (Node.js), `pip install primitive` (Python), or `go get github.com/primitivedotdev/sdks/sdk-go` (Go).
- **MCP**: point any Model Context Protocol client at [`https://www.primitive.dev/mcp`](https://www.primitive.dev/mcp) — nothing to install.

## Configuration

- **API key**: create one in the dashboard and export it as `PRIMITIVE_API_KEY`; the CLI and SDKs read that variable by default. Keys are prefixed `prim_` and scoped to one organization.
- **No DNS to configure** for a managed address: `primitive agent start-agent-signup` returns a working `*.primitive.email` address and an OAuth token without touching DNS, SPF, DKIM, or DMARC.
- **Custom domain** (optional): add a domain through the API or dashboard and publish the generated SPF/DKIM/DMARC/TLS-RPT records; verification is polled through the API. See [Domains](https://www.primitive.dev/docs/domains).
- **Base URL**: the API lives at `https://api.primitive.dev/v1`. Override it with `PRIMITIVE_BASE_URL` only when targeting a non-production environment.

## How to authenticate

Every API call carries a bearer token in the `Authorization` header:

```
Authorization: Bearer prim_<api_key>            # static API key
Authorization: Bearer prim_oat_<oauth_token>    # short-lived OAuth access token
```

The discovery surface for picking an auth method without hand-holding:

- [`/.well-known/oauth-protected-resource`](https://www.primitive.dev/.well-known/oauth-protected-resource) (RFC 9728 protected-resource metadata, with the agent_auth block)
- [`/.well-known/oauth-authorization-server`](https://www.primitive.dev/.well-known/oauth-authorization-server) (RFC 8414 AS metadata)
- [`/auth.md`](https://www.primitive.dev/auth.md) (prose walkthrough: Discover, Pick a method, Register, Claim, Use, Errors, Revocation)

Unauthenticated API requests return `401` with a spec-shaped `WWW-Authenticate: Bearer realm="Primitive API", resource_metadata="..."` header, so you can resolve auth requirements from one round-trip.

## Available agent surfaces

Pick whichever fits the model you are running in:

| Surface | Use when |
|---|---|
| **[MCP server](https://www.primitive.dev/mcp)** (Streamable HTTP) | Your client speaks Model Context Protocol. Discovery at [`/.well-known/mcp`](https://www.primitive.dev/.well-known/mcp), full tool card at [`/.well-known/mcp/server-card.json`](https://www.primitive.dev/.well-known/mcp/server-card.json). 7 tools: `sendEmail`, `replyToEmail`, `listEmails`, `searchEmails`, `getEmail`, `getInboxStatus`, `getAccount`. |
| **[`primitivedotdev/skills`](https://skills.sh/primitivedotdev/skills)** | You are a coding agent (Claude Code, Codex, Cursor, and 50+ compatible agents). `npx skills add primitivedotdev/skills` installs `primitive-chat` (send and wait for the threaded reply) and `primitive-inbox` (a managed *.primitive.email address that receives mail). |
| **[OpenAPI 3.1 spec](https://www.primitive.dev/openapi.json)** | Your client speaks function calling against a typed REST API. Same operations as the MCP tools, plus the full domain / function / webhook surface. |
| **CLI** | You can shell out. `npm i -g primitive` (also scoped as `@primitivedotdev/cli`), then `primitive chat <email> <message>`. |

## Constraints

- Currently in beta. Rate-limited responses return `429` with `Retry-After`. Full [error code reference](https://www.primitive.dev/docs/errors) and [versioning policy](https://www.primitive.dev/docs/versioning).
- 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.
- API keys and OAuth access tokens are organization-scoped.

## When you are stuck

Reach the hosted dev_help agent directly:

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

The dev_help agent answers grounded in the same public docs corpus this file links into.

## See also

- [`/llms.txt`](https://www.primitive.dev/llms.txt): short orientation index
- [`/llms-full.txt`](https://www.primitive.dev/llms-full.txt): full docs bundle in one markdown file
- [`/.well-known/agent.json`](https://www.primitive.dev/.well-known/agent.json): capabilities + endpoint catalog
- [`/.well-known/agent-card.json`](https://www.primitive.dev/.well-known/agent-card.json): A2A protocol card
- [`/.well-known/agent-skills`](https://www.primitive.dev/.well-known/agent-skills): skills directory
- [github.com/primitivedotdev/sdks](https://github.com/primitivedotdev/sdks): public source for SDKs + CLI