# primitive

> The email layer for AI agents. Send and receive email with one HTTP call, host an agent at a managed *.primitive.email address, and chat agent-to-agent over email with a single verb.

## What it is

Primitive is email infrastructure built for AI agents:

- `primitive chat <email> <message>` — send a message and wait for the threaded reply. Round-trip in one verb.
- Managed `*.primitive.email` subdomains with a JavaScript handler that runs on every inbound message.
- Full v1 REST API for send, receive, domain management, and function hosting.

API base: `https://api.primitive.dev/v1`
Auth: `Authorization: Bearer prim_<api_key>` or `Bearer prim_oat_<oauth_token>`

## When to use Primitive

Reach for Primitive when an agent needs to:

- Send a message and wait for a person or another agent to reply on the same thread (use [primitive chat](https://www.primitive.dev/docs/cli) or the [/send-mail API](https://www.primitive.dev/docs/sending)).
- Host an inbound address that runs a JavaScript handler on every received email (see [Functions](https://www.primitive.dev/docs/functions)).
- Get a working email identity without buying a domain, configuring DNS, or copying SMTP credentials into an agent context (the managed [\*.primitive.email subdomain](https://www.primitive.dev/docs/managed-inbox)).
- Send transactional email from a custom domain with managed SPF, DKIM, DMARC, and TLS-RPT (see [Domains](https://www.primitive.dev/docs/domains)).
- Expose an agent over the universal addressing scheme every business already uses (one signup at [https://www.primitive.dev/signup](https://www.primitive.dev/signup)).

## How it compares

- vs. SMTP: no credentials, no app passwords, no port-25 firewall battles. One HTTPS call.
- vs. Resend / SendGrid / Mailgun: built for two-way agent conversations, not just outbound transactional sends. Inbound MX and a JavaScript handler ship in the same product.
- vs. building your own MX: Primitive is the MX. SPF, DKIM, DMARC, TLS-RPT, IP reputation, and bounce processing are managed.

## Constraints

- Currently in beta. Rate-limited API 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) in the docs.
- Inbound email contents are retained for 30 days unless attached to a Function execution.
- API keys and OAuth access tokens are organization-scoped.

## Quickstart

- [Quickstart walkthrough](https://www.primitive.dev/docs/quickstart)
- [Agent auth guide](https://www.primitive.dev/auth.md)
- [Sign up](https://www.primitive.dev/signup)
- [Pricing reference](https://www.primitive.dev/pricing.md)

## Install

- CLI: `npm i -g @primitivedotdev/cli`
- Skill (Claude Code, Codex CLI, OpenCode, Amp): `npx skills add primitivedotdev/chat`
- Node SDK: `npm i @primitivedotdev/sdk`
- Python SDK: `pip install primitive`
- Go SDK: `go get github.com/primitivedotdev/sdks/sdk-go@latest`

## Public code

Primitive's SDKs, CLI, and inbound MX are public source:

- [github.com/primitivedotdev/sdks](https://github.com/primitivedotdev/sdks): Node, Python, and Go SDKs plus the `primitive` CLI, all generated from the same OpenAPI spec. Includes [`AGENTS.md`](https://github.com/primitivedotdev/sdks/blob/main/AGENTS.md) at the repo root with codebase conventions for AI coding agents.
- [github.com/primitivedotdev/primitivemail](https://github.com/primitivedotdev/primitivemail): the inbound MX implementation. Public so customers can audit or self-host the same mail intake we operate.
- [npmjs.com/org/primitivedotdev](https://www.npmjs.com/org/primitivedotdev): published npm packages.
- [skills.sh/primitivedotdev/chat](https://skills.sh/primitivedotdev/chat): the `primitive chat` skill for compatible coding agents.

## Machine-readable surfaces

- [OpenAPI 3.1 spec](https://www.primitive.dev/openapi.yaml) (also [JSON](https://www.primitive.dev/openapi.json))
- [MCP server](https://www.primitive.dev/mcp) (Streamable HTTP transport)
- [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)](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)
- [Full docs bundle](https://www.primitive.dev/llms-full.txt) (text/markdown)

## Help

Stuck? Ask the dev_help agent directly:

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

That round-trips through the same hosted MCP / API surface this file documents, with answers grounded in [the docs corpus](https://www.primitive.dev/docs).