agent communication built on what already works

Overview

Primitive is email infrastructure built for AI agents. It provides one-call HTTP email sending and receiving, managed *.primitive.email addresses that run a JavaScript handler on every inbound message, and an agent-to-agent chat verb that returns the threaded reply without SMTP credentials. The product removes the protocol surface an agent would otherwise operate: inbound MX, SPF, DKIM, DMARC, TLS-RPT, bounce processing, and sending-IP reputation are all managed, so an agent reaches people and other agents over ordinary email without standing up a mail server or placing SMTP credentials in its context.

Capabilities

HTTP email

A v1 REST API and an MCP server cover email sending, receiving, domain management, filters, webhook endpoints, and function hosting.

Managed inbound addresses

Each managed *.primitive.email subdomain is a real, receivable address the owning agent controls. It runs a JavaScript handler on every received message, so other agents and people can reach an agent at a normal email address.

Agent-to-agent chat

The primitive chat verb delivers a message and returns the threaded reply in a single round trip.

Sending email

Outbound mail is sent with a single authenticated HTTPS request. A request carries the sender, recipients, subject, and a text or HTML body, and may include attachments. Sends are asynchronous and return a message identifier for status tracking. Retries are safe: a request that carries an idempotency key is de-duplicated, so a retried send never produces a duplicate message. Outbound traffic is rate limited per organization for abuse control, and a rate-limited response carries the interval before a retry is accepted.

Receiving email

Inbound messages are delivered to a webhook endpoint or processed by a hosted JavaScript function that runs on every received message. The function model keeps inbound logic on Primitive infrastructure rather than an always-on consumer the developer operates. Inbound message contents are retained until you delete them; Primitive does not auto-delete stored mail on a schedule.

Custom domains and routing

Beyond the managed subdomains, a custom domain can be connected for transactional sending and receiving. Domain authentication records — SPF, DKIM, DMARC, and TLS-RPT — are generated and verified through the API, and filters route inbound mail to webhook endpoints or hosted functions.

Authentication

Every API request carries a bearer token: an API key prefixedprim_ or an OAuth access token prefixed prim_oat_. Tokens are scoped to an organization. An agent self-serves a credential through a signup flow that verifies an email address and returns an OAuth access token. Authorization-server and protected-resource metadata are published at the conventional .well-known locations, so an agent discovers how to authenticate without human setup.

For developers

Primitive provides a v1 REST API described by an OpenAPI 3.1 specification, a hosted Model Context Protocol server, a Microsoft NLWeb query endpoint, a command-line tool, and Node, Python, and Go software development kits generated from the same specification. The REST surface covers sending, receiving, domain management, filters, webhook endpoints, inbox status, and function hosting.

Discovery and machine-readable surfaces

Primitive publishes machine-readable descriptions of itself so an agent discovers and uses it without documentation: an OpenAPI specification, an llms.txt orientation file, a Model Context Protocol discovery document and server card, an agent card, an API catalog, and OAuth metadata, each at a predictable URL. The Model Context Protocol server is also listed in public registries.

Reliability and deliverability

Deliverability is handled as managed infrastructure. Outbound mail is signed and authenticated, bounces and complaints are processed automatically, and sending-IP reputation is maintained by Primitive. Inbound mail passes spam and policy filtering before delivery. An agent inherits production-grade deliverability without operating a mail server or warming an IP address.

Typical uses

Primitive suits an AI agent that needs its own email identity rather than access to a person’s existing mailbox. Representative situations include an agent that sends a message and waits for a person or another agent to reply on the same thread, an agent that exposes a contact address running custom logic on every inbound message, an agent that sends transactional email from a custom domain with managed authentication, and a system that gives many short-lived agents their own addresses without per-mailbox setup.

API conventions

The REST surface is versioned under the /v1 path and accepts and returns JSON. Errors share one typed model: a stable machine-readable code, a human-readable message, and an HTTP status, so a client branches on the code rather than parsing prose. Listing endpoints return a consistent pagination envelope, and long-running work follows an asynchronous job pattern in which a send returns a message identifier that a client polls for delivery status. A rate-limited request returns HTTP 429 with a Retry-After header and the remaining quota rather than a hard failure, so a client backs off deterministically. A request that carries an idempotency key is de-duplicated, so a retried send never produces a duplicate message, and a batch endpoint accepts many messages in one authenticated call.

SDKs and integration surfaces

Three official software development kits — for Node.js, Python, and Go — are generated from the same OpenAPI 3.1 specification, so their types and method names stay in lock-step with the REST API. A command-line tool wraps the same surface for shell and agent use, including a single chat verb that sends a message and returns the threaded reply. The hosted Model Context Protocol server exposes the same surface over Streamable HTTP, covering sending, reading, and search alongside domain, endpoint, and filter management, and a Microsoft NLWeb endpoint answers natural-language queries against the same data. Webhook deliveries are signed, so a receiver verifies authenticity before acting on an inbound message.

Editor and agent integrations

The hosted Model Context Protocol server is a standard Streamable HTTP endpoint with OAuth, so any MCP-compatible client connects to it and uses the same email tools without a vendor-specific plugin. Compatible clients include Claude (claude.ai, Claude Desktop, and Claude Code), Cursor, Visual Studio Code (VS Code) in GitHub Copilot agent mode, and Goose, the open-source agent from Block. ChatGPT-compatible runtimes use the published plugin manifest instead. The primitive-chat and primitive-inbox skills additionally install into Claude Code, Codex, Cursor, and other coding agents from a single command. The integration is the open protocol itself, so no per-client integration work is required.

Frequently asked questions

What is Primitive?

Primitive is email infrastructure for AI agents. It sends and receives email via a REST API, hosts an agent at a managed *.primitive.email subdomain, and reaches any address with the one-line primitive chat verb.

How do agents authenticate?

Every API request carries Authorization: Bearer prim_<api_key> or Authorization: Bearer prim_oat_<oauth_access_token>. Discovery metadata is published at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource; the full walkthrough is at https://www.primitive.dev/auth.md.

Does Primitive have an MCP server?

Yes. The hosted Model Context Protocol server is at https://www.primitive.dev/mcp (Streamable HTTP, stateless). Discovery at /.well-known/mcp and full server card at /.well-known/mcp/server-card.json. Seven tools: sendEmail, replyToEmail, listEmails, searchEmails, getEmail, getInboxStatus, getAccount.

What does Primitive cost?

Primitive has three usage-based tiers: a free Developer tier ($0/mo with $5/mo of usage credits), Power ($13/mo with $13/mo of credits), and Platinum ($299/mo with $299/mo of credits). Inbound and outbound email, storage, function invocations, and function runtime are metered against your monthly credits, and usage beyond them is billed. Full breakdown at https://www.primitive.dev/pricing.md.

Is Primitive open source?

The SDKs and CLI are public at https://github.com/primitivedotdev/sdks (Node, Python, Go, all generated from one OpenAPI spec). The hosted services run on Primitive infrastructure.

primitive.dev
Backed by Y Combinator

primitive gives agents a managed email surface: send mail through an authenticated API, receive mail at managed addresses, and run hosted functions on inbound messages.

get starteddocsblogtalk to us

email for any agent, with complete control

drop one verb into any CLI agent. it sends mail, waits for the threaded reply, and hands the response back.

$ npx skills add primitivedotdev/skills
$ primitive chat dev@agent.primitive.dev '<literally anything>'
SDKs/CLI on GitHub
↳ replied in 4s with "thanks, taking a look"

simply the best transactional email infra

we parse attachments, verify DKIM and SPF, decode SMTP envelopes, split headers. you don't have to own any infra just to work with email anymore.

inbound webhook
{
  "event": "email.received",
  "from": "sender@example.com",
  "to": "agent@you.primitive.email",
  "subject": "Hello from Primitive",
  "body": "Quick question about..."
}

full synchronous outbound. we open SMTP straight to the receiving server, so the response code and their queue ID come back in your same call. a true developer primitive.

outbound api response
{
  "id": "e3a8f9b2-4d1c-4b71-9c5a-2f8b3e1d7a4c",
  "status": "delivered",
  "accepted": ["alice@customer.com"],
  "queue_id": "47B2D7A1F0",
  "smtp_response_code": 250,
  "smtp_response_text": "2.0.0 Ok: queued as 47B2D7A1F0"
}

fully hosted agents

write a handler. deploy with one command. primitive runs it on every inbound email, no servers to manage.

$ primitive functions:init my-fn
$ primitive functions:deploy --name my-fn --source .
↳ deployed in 421ms to my-fn.primitive.email

built on our own infra

every hop in the email pipeline runs on primitive-owned servers, end-to-end.

inbound
senderMXparser
functionsyour webhook handler
outbound
POST/send-mail
SMTP relaydirect delivery
recipient MX
direct delivery returns recipient's 250 OK + queue id in the same request
green = primitive-owned bare metal. no third party in the path.

email infrastructure built for agents

primitive gives agents a managed email surface: send mail through an authenticated API, receive mail at managed addresses, and run hosted functions on inbound messages. the public docs include markdown mirrors, OpenAPI specs, OAuth discovery metadata, and an auth walkthrough so agents can integrate without scraping the dashboard.

API base
https://api.primitive.dev/v1
auth
bearer API keys and OAuth access tokens. see the Primitive authentication docs or auth.md.
specs
Primitive API reference, OpenAPI YAML and OpenAPI JSON.

send and receive

use the REST API, SDKs, CLI, or MCP server for sending. route inbound mail to webhooks or hosted functions.

managed addresses

start with a managed *.primitive.email address, then add custom domains when DNS control matters.

agent-readable docs

fetch index.md, llms.txt, or llms-full.txt for markdown context.

You've Got Mail!Read: launch week, release 05