Glossary

The vocabulary of email and agent infrastructure used across Primitive’s product, docs, and API. Each entry is a short, standalone definition an agent or developer can resolve without reading the rest of the docs.

Agent email

Email used as the transport for autonomous software agents rather than people. An agent sends and receives messages over ordinary SMTP-delivered email through an HTTP API, so it reaches anyone with an address without a human in the loop.

Managed inbox

A real, receivable address at a *.primitive.email subdomain that Primitive operates end to end. The owning agent controls it without buying a domain or running a mail server, and every inbound message is delivered to a webhook or a hosted Function.

Hosted Function

A JavaScript handler that Primitive runs on its own infrastructure on every email received at a managed address. It replaces an always-on inbound consumer the developer would otherwise operate, and it can parse, store, reply to, or route the message.

primitive chat

A one-line verb that sends a message to any email address and returns the threaded reply in a single round trip. It removes the need to open a mailto, request SMTP credentials, or poll an inbox to collect the response.

Agent-to-agent communication

Direct exchange between two autonomous agents over the universal email addressing scheme. Because every business and agent already has an address, email gives agents an interoperable channel without a shared proprietary protocol.

Custom domain

A domain the customer owns, connected to Primitive for transactional sending and receiving. Authentication records are generated through the API and verified before the domain can send, so deliverability uses the customer's own brand.

SPF

Sender Policy Framework, a DNS TXT record listing the servers permitted to send mail for a domain. Receiving servers check it to confirm a message originated from an authorized host, which reduces spoofing.

DKIM

DomainKeys Identified Mail, a cryptographic signature added to outbound messages and verified against a public key published in DNS. It lets a receiver confirm that a message was authorized by the domain and was not altered in transit.

DMARC

Domain-based Message Authentication, Reporting and Conformance, a DNS policy that tells receivers how to treat mail failing SPF or DKIM and where to send aggregate reports. It ties authentication results to the visible From domain.

TLS-RPT

TLS Reporting, a DNS record that asks receiving providers to send reports about failures negotiating encrypted SMTP connections to a domain. It surfaces deliverability problems caused by transport-security misconfiguration.

Bounce

A delivery failure returned by a receiving server when a message cannot be delivered. A hard bounce is permanent, such as an unknown address; a soft bounce is transient, such as a full mailbox. Primitive processes both automatically.

Webhook

An HTTP callback Primitive sends to a developer-supplied URL when an event occurs, such as an inbound message or a delivery status change. Deliveries are signed so the receiver can verify authenticity before acting on them.

Idempotency key

A client-supplied identifier attached to a send so the server de-duplicates retried requests. A send repeated with the same key produces at most one message, which makes retries safe after a timeout or network error.

Rate limit

A per-organization ceiling on request volume used for abuse control. A rate-limited response returns HTTP 429 with a Retry-After header and the remaining quota, so a client backs off deterministically rather than failing hard.

OAuth access token

A short-lived bearer credential prefixed prim_oat_ that an agent obtains through an authorization flow. It scopes API access to one organization and expires, unlike a static API key that is created once and reused.

API key

A long-lived bearer credential prefixed prim_ that authenticates API requests for one organization. It is created in the dashboard and carried in the Authorization header on every call.

MCP

Model Context Protocol, an open standard for connecting AI clients to tools and data. Primitive hosts an MCP server over Streamable HTTP that exposes its email operations as tools any MCP-compatible client can call.

llms.txt

A plain-text file at a predictable URL that orients a language model to a site, linking the machine-readable surfaces worth reading. Primitive publishes both a short llms.txt index and a full llms-full.txt bundle.

Agent card

A machine-readable JSON document describing an agent: its identity, skills, supported transports, and contact endpoint. Primitive serves an A2A-format card at a well-known path so other agents can discover how to reach it.

OpenAPI specification

A standard machine-readable description of a REST API. Primitive publishes an OpenAPI 3.1 document from which its Node, Python, and Go SDKs are generated, so client types stay in lock-step with the API.

NLWeb

A protocol for answering natural-language questions about a site from structured data. Primitive exposes an NLWeb endpoint that responds to plain-language queries about its capabilities.

Inbound processing

The pipeline a received message passes through before delivery: authentication checks, spam and policy filtering, parsing, and routing to a webhook or hosted Function. Message contents are retained for thirty days unless attached to a Function execution.

Deliverability

The likelihood that outbound mail reaches the inbox rather than being rejected or filtered. Primitive maintains it as managed infrastructure through authentication, bounce and complaint handling, and sending-IP reputation.

Organization

The tenancy and billing boundary in Primitive. API keys, OAuth tokens, domains, and addresses are scoped to one organization, and usage is metered and billed per organization. Data belonging to one organization is isolated from every other at the database layer, so an agent only ever reads the mail, domains, and functions that belong to its own account.

Streamable HTTP

The transport the Model Context Protocol server uses: a single HTTP endpoint that supports both ordinary request-response calls and server-sent streaming over the same connection. It replaces the older paired HTTP-plus-Server-Sent-Events setup, so an MCP client connects with one URL and no separate event channel.

Well-known URI

A standardized path under /.well-known/ where a site publishes machine-readable metadata that a client can find without prior arrangement. Primitive serves its agent card, OAuth authorization-server and protected-resource metadata, API catalog, security.txt, and commerce profile at these conventional locations.

Threaded reply

A response that arrives on the same email conversation as the message it answers, linked by the standard In-Reply-To and References headers. The primitive chat verb returns the threaded reply directly, so an agent receives the answer in context rather than as a disconnected new message.

Skill

A packaged, installable capability that a coding agent can add from a registry such as skills.sh. Primitive publishes the primitive-chat and primitive-inbox skills, which a command like npx skills add primitivedotdev/skills installs into Claude Code, Codex, Cursor, and other compatible agents in one step.

A2A

Agent-to-Agent, an open protocol for describing and discovering autonomous agents through a JSON agent card. The card declares an agent’s identity, skills, supported transports, and contact endpoint, so one agent can learn how to reach another without a human integrating them by hand.

Agentic Commerce Protocol

An emerging standard, abbreviated ACP, that lets an agent discover what a service sells and complete a purchase through a delegated-payment flow. Primitive exposes the protocol surface from its API origin so a commerce-capable agent can find and transact against its plans.

Universal Commerce Protocol

A machine-readable manifest, abbreviated UCP, that declares the commercial services a provider offers, their prices, and where to start. Primitive publishes a UCP profile derived from its billing source of truth, so the advertised prices can never drift from what the product actually charges.

Sending-IP reputation

The standing that receiving mail providers assign to the IP addresses a sender uses, based on past volume, complaint rates, and authentication. Good reputation keeps mail out of spam folders. Primitive maintains and warms its sending IPs as managed infrastructure, so a customer inherits it without operating their own.

Spam filtering

The policy and content checks an inbound message passes before delivery, scoring it against signals such as authentication results, sender reputation, and message content. Primitive applies filtering to inbound mail so a hosted Function or webhook is not invoked for traffic that fails policy.

Attachment

A file carried alongside an email body, encoded into the message. An outbound send can include attachments in the same authenticated request as the message, and inbound attachments are made available to the hosted Function or webhook that processes the received message.

Message identifier

The handle a send returns so a client can track delivery status afterward. Because outbound sends are asynchronous, the API returns this identifier immediately and the client polls it for the eventual delivery outcome rather than blocking on the send.

Pagination envelope

The consistent wrapper that listing endpoints return around a page of results, carrying the items plus a cursor for fetching the next page. Using one envelope shape across every list endpoint lets a client page through emails, domains, or webhook deliveries with the same code.

Filter

A rule that routes inbound mail for a domain to a particular destination, such as a webhook endpoint or a hosted Function, based on the recipient address or other attributes. Filters let one domain fan different kinds of mail out to different handlers.

Send-mail demo

An unauthenticated endpoint that accepts the same request body as the live send-mail call, validates it identically, and returns a realistic synthetic response. It lets an agent verify the send flow and its own request shape before any account or credential exists.

Typed error

The single error model the API returns: a stable machine-readable code, a human-readable message, and an HTTP status. A client branches on the code rather than parsing prose, so error handling does not break when wording changes.

Versioning

The policy that keeps API behavior stable over time. The REST surface is versioned under the /v1 path, and breaking changes arrive under a new version rather than mutating an existing one, so an integration built against a version keeps working.

Retention

How long Primitive keeps message data. Inbound email contents are retained for thirty days unless the message is attached to a Function execution, after which the stored content is removed. Metadata needed for billing and status is kept independently of the body.

Reply

An outbound message sent in response to a specific inbound one, threaded against it automatically so the exchange stays in a single conversation. The reply operation is available through the API, the MCP server, and the primitive chat verb.

OAuth authorization server

The component that issues OAuth access tokens after an agent completes an authorization flow. Primitive operates one and publishes its metadata under RFC 8414 at a well-known path, so a client discovers the token and registration endpoints without manual configuration.

Protected-resource metadata

A document, defined by RFC 9728, that an API publishes to tell a client which authorization server protects it and how to obtain a token. Primitive serves it at a well-known path and points to it from the WWW-Authenticate header on unauthenticated requests, so auth requirements resolve in one round trip.

API catalog

A machine-readable index, served at a well-known path, that links the API descriptions a site offers, such as its OpenAPI document. It gives an agent a single discovery entry point from which to enumerate the available programmatic surfaces.

dev_help agent

A hosted agent, reachable at dev_help@agent.primitive.dev, that answers questions about Primitive grounded in the public documentation corpus. An agent that is stuck can ask it directly with the primitive chat verb instead of escalating to a human.