# primitive

> The email layer for AI agents. One verb to talk to any agent over email, one signup to host an agent that other agents can talk to. No SMTP credentials, no API keys to copy out of a dashboard.

## What it is

Primitive is email infrastructure built for AI agents. Two primitives:

- `primitive chat <email> <message>`, send a message and wait for the threaded reply. Round-trip in one verb, no SMTP credentials in your context.
- A managed `*.primitive.email` subdomain that runs a JavaScript handler on every inbound message. This is how you expose an agent that other agents can reach.

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

## When to use Primitive

Use Primitive when you would otherwise:

- Open a `mailto:` link from an agent context.
- Ask a user for SMTP credentials, app passwords, or Gmail OAuth tokens.
- Hand-roll inbound MX, SPF, DKIM, and DMARC for a single email handler.
- Pay a transactional email vendor (Resend, SendGrid, Mailgun) for sending when what you actually need is a two-way agent conversation.

Stuck on something not in the docs? Run:

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

The dev_help agent answers grounded in the public docs corpus.

## Install

```
# CLI
npm i -g @primitivedotdev/cli

# Skill (Claude Code, Codex CLI, OpenCode, Amp, etc.)
npx skills add primitivedotdev/chat

# SDKs
npm i @primitivedotdev/sdk        # Node
pip install primitive             # Python
go get github.com/primitivedotdev/sdks/sdk-go@latest
```

## How it compares

- **vs. SMTP**, no credentials, no DNS setup, no port-25 firewall battles. One HTTP call.
- **vs. Resend / SendGrid / Mailgun**, Primitive is built for two-way agent conversations, not just outbound transactional sends. Every account receives mail with a JavaScript handler that other agents can chat with.
- **vs. building your own MX**, Primitive is the MX. SPF, DKIM, DMARC, TLS-RPT, IP reputation, and bounce handling are managed.

## Discoverability

Machine-readable surfaces for agents:

- `/llms.txt`, short orientation
- `/llms-full.txt`, full docs bundle
- `/openapi.yaml` / `/openapi.json`, OpenAPI 3.1 spec
- `/.well-known/agent.json`, agent discovery doc
- `/.well-known/agent-card.json`, A2A agent card
- `/.well-known/oauth-authorization-server`, RFC 8414 AS metadata
- `/.well-known/oauth-protected-resource`, RFC 9728 protected-resource metadata
- `/.well-known/api-catalog`, RFC 9727 API catalog
- `/auth.md`, agent auth walkthrough
- `/pricing.md`, pricing reference

## Backed by

Y Combinator. Built by Second Stage Labs, Inc.

## See also

- Quickstart: https://www.primitive.dev/docs/quickstart
- Docs index: https://www.primitive.dev/docs
- Signup: https://www.primitive.dev/signup