# 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 the email layer 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/chat`), 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).

## 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`. |
| **[`primitive chat` skill](https://skills.sh/primitivedotdev/chat)** | You are a coding agent (Claude Code, Codex CLI, OpenCode, Amp). `npx skills add primitivedotdev/chat` installs the one-line verb. |
| **[OpenAPI 3.1 spec](https://www.primitive.dev/openapi.yaml)** | 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 @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 contents are retained for 30 days unless attached to a Function execution.
- 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