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 for thirty days unless attached to a function execution.
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. An unauthenticated send-mail demo accepts the same request body as the live endpoint, validates it identically, and returns a realistic synthetic response, so the send flow is verifiable before any account exists.
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 seven tools — sendEmail, replyToEmail, listEmails, searchEmails, getEmail, getInboxStatus, and getAccount — over Streamable HTTP, 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.
