Primitive

Primitive is email infrastructure built for AI agents. It lets an agent send and receive email with a single authenticated HTTP call — no SMTP credentials, DNS, or mail servers — and hosts each agent at a managed *.primitive.email address that runs a JavaScript handler on every inbound message. The `primitive chat` verb sends a message and returns the threaded reply in one round trip. The v1 REST API (96 paths, 129 operations) covers domains, sending, inbound emails, threads, search, webhook endpoints, filters, routing, hosted Functions, durable Memories, an agent registry, wake scheduling, and non-custodial x402 USDC payments over email. Primitive ships a published hosted MCP server, an A2A agent card, a read-only GraphQL surface, official Node/Python/Go SDKs and a CLI, and a rich agent-native discovery surface (llms.txt, /.well-known/*, packaged Agent Skills). Backed by Y Combinator (Spring 2026).

Primitive publishes 22 APIs on the APIs.io network, including Account API, Agent API, CLI API, and 19 more. Tagged areas include Email, Email Infrastructure, AI Agents, Agent Infrastructure, and Messaging.

The Primitive catalog on APIs.io includes 1 event-driven AsyncAPI specification.

Primitive’s developer surface includes documentation, API reference, getting-started guide, signup flow, pricing, engineering blog, support, and 28 more developer resources.

🌐 Visit website 📡 Source on GitHub
58.2/100 developing ▬ flat Agent 87/100 agent native Full breakdown ↓
scored 2026-07-27 · rubric v0.5
AccessSelf serve
22 APIs 1 MCP Servers
EmailEmail InfrastructureAI AgentsAgent InfrastructureMessagingWebhooksMCPDeveloper ToolsAPI

Kin Score

Kin Score Kin Score How this is scored →
scored 2026-07-27 · rubric v0.5
Composite quality — 58.2/100 · developing
Contract Quality 17.8 / 25
Developer Ergonomics 17.4 / 20
Commercial Clarity 8.9 / 20
Operational Transparency 4.1 / 13
Governance 0.0 / 12
Discoverability 10.0 / 10
Agent readiness — 87/100 · agent native
Machine-Readable Contract 18 / 18
Agentic Access Contract 15 / 15
MCP Server 12 / 12
Machine-Readable Auth 10 / 10
Idempotency 9 / 9
Stable Error Semantics 8 / 8
Request/Response Examples 0 / 7
Rate-Limit Signaling 0 / 7
Typed Event Surface 6 / 6
Agent Skills 5 / 5
Well-Known Catalog 4 / 4
Consent & Bot Identity 3 / 3
Improve this rating by publishing the missing artifacts — every area above can be raised, and the full rubric is at apis.io/rating/. This rating is computed from github.com/api-evangelist/primitive: open an issue to ask a question, or submit a pull request to add artifacts. Want it done for you? Prioritized profiling — $2,500 →

APIs 22

Individual APIs this provider publishes, each with its own machine-readable definition.

Primitive Account API

Manage your account settings, storage, and webhook secret

Primitive Agent API

Agent signup and authentication

Primitive CLI API

Browser-assisted CLI authentication

Primitive Demo API

Public, no-account sandbox operations that mirror authenticated endpoints with synthetic data so an agent can learn the request and response shapes before signing up.

Primitive Discovery API

Unauthenticated entry point that lists the API base URL, how to obtain credentials, and the operations callable without a token.

Primitive Domains API

Claim, verify, and manage email domains

Primitive Emails API

List, inspect, and manage received emails

Primitive Endpoints API

Manage webhook endpoints that receive email events

Primitive Filters API

Manage whitelist and blocklist filter rules

Primitive Functions API

Deploy JavaScript handlers that run on inbound mail. Each function is a single ESM module whose default export is an object with an async `fetch(request, env)` method, in the sh...

Primitive Inbox API

Check inbound email setup and processing readiness

Primitive Memories API

Durable org-scoped or function-scoped JSON key-value storage for agents and functions. Keys are caller-defined. Function scope is always addressed by the function id UUID, not b...

Primitive Payments API

Collect and pay stablecoin (USDC) payments with x402. Settlement is non-custodial: funds move directly from payer to payee on-chain via an EIP-3009 authorization the payer signs...

Primitive Registries API

The Agent Registry: ownable directories of agents, addressable by a registry-scoped handle. A registry's publish policy (owner_only, request, or open) decides whether a publish ...

Primitive Routes API

Recipient routing: route inbound mail to a single destination per recipient address. Rules bind an address pattern (exact or wildcard) to an endpoint; `function_id` routes an ad...

Primitive Search API

Semantic and hybrid search across received and sent mail

Primitive Sending API

Send outbound emails through the Primitive API

Primitive Service API

Operational endpoints such as the unauthenticated health/liveness probe.

Primitive Templates API

Public Function template registry reads used to browse installable agent templates.

Primitive Threads API

Conversation threads spanning received and sent emails

Primitive Wake API

Wake scheduling: schedule and send typed wake commands to your own functions over real DKIM-signed email on a cron cadence, and manage the per-target allowlist that authorizes w...

Primitive Webhook Deliveries API

View and replay webhook delivery attempts

Scroll for all 22

MCP Servers 1

Model Context Protocol servers that expose these APIs to AI agents.

primitive-mcp.yml

MCP SERVER

Event Specifications 1

AsyncAPI definitions for this provider's event-driven and streaming APIs.

Primitive Webhooks

ASYNCAPI

Security Posture 3

Authentication, domain security, vulnerability disclosure, and trust-center signals.

Primitive Authentication

apiKey/http · 2 schemes

SECURITY

Primitive Domain Security

TLSv1.3 · HSTS · DNSSEC · DMARC

SECURITY

Primitive Vulnerability Disclosure

security.txt · contact published

SECURITY

Agentic Access 1

Recommended x-agentic-access execution contracts for AI agents.

Primitive Agentic Access

129 operations · 76 acting · 1 human-in-the-loop

129 operations · 76 acting

AGENTIC

Resources

Get Started 4

Portal, sign-up, and the first successful call

DeveloperPortal
DeveloperPortal
 GettingStarted
GettingStarted
 SignUp
SignUp
 Sandbox
Sandbox

Documentation 2

Reference material describing how the API behaves

Documentation
Documentation
 APIReference
APIReference

Agent Surfaces 5

MCP servers, agent skills, and machine-readable catalogs

MCPServer
MCPServer
 AgentSkill
AgentSkill
 LLMsTxt
LLMsTxt
 WellKnown
WellKnown
 AgenticAccess
AgenticAccess

Design & Contract 8

Pagination, idempotency, versioning, errors, and events

Conventions
Conventions
 Idempotency
Idempotency
 ErrorCatalog
ErrorCatalog
 Lifecycle
Lifecycle
 Webhooks
Webhooks
 Components
Components
 DataModel
DataModel
 Conformance
Conformance

Scroll for all 8

Build 4

SDKs, sample code, and the tooling you integrate with

GitHubOrganization
GitHubOrganization
 Packages
Packages
 SDKs
SDKs
 CLI
CLI

Access & Security 5

Authentication, authorization, and security posture

SecurityTxt
SecurityTxt
 Authentication
Authentication
 VulnerabilityDisclosure
VulnerabilityDisclosure
 Security
Security
 DomainSecurity
DomainSecurity

Operate 2

Status, limits, changes, and where to get help

Support
Support
 Deprecation
Deprecation

Commercial 3

Pricing, plans, and the legal terms of use

Pricing
Pricing
 TermsOfService
TermsOfService
 PrivacyPolicy
PrivacyPolicy

Company 1

The organization behind the API

Blog
Blog

Other 1

Properties that don't map to a standard resource type

Overlay
Overlay

Source (apis.yml)

apis.yml Raw ↑ 
aid: primitive
name: Primitive
description: Primitive is email infrastructure built for AI agents. It lets an agent send and receive email with a single
  authenticated HTTP call — no SMTP credentials, DNS, or mail servers — and hosts each agent at a managed *.primitive.email
  address that runs a JavaScript handler on every inbound message. The `primitive chat` verb sends a message and returns the
  threaded reply in one round trip. The v1 REST API (96 paths, 129 operations) covers domains, sending, inbound emails, threads,
  search, webhook endpoints, filters, routing, hosted Functions, durable Memories, an agent registry, wake scheduling, and
  non-custodial x402 USDC payments over email. Primitive ships a published hosted MCP server, an A2A agent card, a read-only
  GraphQL surface, official Node/Python/Go SDKs and a CLI, and a rich agent-native discovery surface (llms.txt, /.well-known/*,
  packaged Agent Skills). Backed by Y Combinator (Spring 2026).
url: https://raw.githubusercontent.com/api-evangelist/primitive/refs/heads/main/apis.yml
accessModel:
  pricing: unknown
  onboarding: self-serve
  trial: false
  try_now: false
  public: false
  label: Self-serve signup
  confidence: medium
  source:
  - authentication
  generated: '2026-07-22'
  method: derived
image: https://www.primitive.dev/web-app-manifest-192x192.png
x-type: company
x-source: vc-portfolio
x-backed-by:
- y-combinator
x-tier: stub
x-tier-reason: portfolio-lead
specificationVersion: '0.20'
created: '2026-07-17'
modified: '2026-07-20'
x-enrichment:
  date: '2026-07-20'
  status: enriched
  artifacts_added: 22
  pass: local-v1
tags:
- Email
- Email Infrastructure
- AI Agents
- Agent Infrastructure
- Messaging
- Webhooks
- MCP
- Developer Tools
- API
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com
- FN: APIs.json
  email: info@apis.io
apis:
- aid: primitive:primitive-account-api
  name: Primitive Account API
  description: Manage your account settings, storage, and webhook secret
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Account
  properties:
  - type: OpenAPI
    url: openapi/primitive-account-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-agent-api
  name: Primitive Agent API
  description: Agent signup and authentication
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Agent
  properties:
  - type: OpenAPI
    url: openapi/primitive-agent-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-cli-api
  name: Primitive CLI API
  description: Browser-assisted CLI authentication
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - CLI
  properties:
  - type: OpenAPI
    url: openapi/primitive-cli-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-demo-api
  name: Primitive Demo API
  description: Public, no-account sandbox operations that mirror authenticated endpoints with synthetic data so an agent can
    learn the request and response shapes before signing up.
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Demo
  properties:
  - type: OpenAPI
    url: openapi/primitive-demo-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-discovery-api
  name: Primitive Discovery API
  description: Unauthenticated entry point that lists the API base URL, how to obtain credentials, and the operations callable
    without a token.
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Discovery
  properties:
  - type: OpenAPI
    url: openapi/primitive-discovery-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-domains-api
  name: Primitive Domains API
  description: Claim, verify, and manage email domains
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Domains
  properties:
  - type: OpenAPI
    url: openapi/primitive-domains-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-emails-api
  name: Primitive Emails API
  description: List, inspect, and manage received emails
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Emails
  properties:
  - type: OpenAPI
    url: openapi/primitive-emails-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-endpoints-api
  name: Primitive Endpoints API
  description: Manage webhook endpoints that receive email events
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Endpoints
  properties:
  - type: OpenAPI
    url: openapi/primitive-endpoints-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-filters-api
  name: Primitive Filters API
  description: Manage whitelist and blocklist filter rules
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Filters
  properties:
  - type: OpenAPI
    url: openapi/primitive-filters-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-functions-api
  name: Primitive Functions API
  description: 'Deploy JavaScript handlers that run on inbound mail. Each function

    is a single ESM module whose default export is an object with an

    async `fetch(request, env)` method, in the shape of a Workers-style

    handler. Primitive signs each delivery and forwards the

    `Primitive-Signature` header to the handler; verify the raw request

    body with `PRIMITIVE_WEBHOOK_SECRET` before trusting the parsed event.

    The `event` field is `email.received` for normal inbound mail, or a

    machine-mail type (`email.bounced`, `email.tls_report`,

    `email.dmarc_report`, `email.dmarc_failure`) for bounces and reports;

    the payload shape is otherwise identical. Code runs on

    Primitive''s edge runtime; there is no infrastructure to manage.

    Secrets land in `env` as encrypted bindings and are refreshed on

    every redeploy.'
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Functions
  properties:
  - type: OpenAPI
    url: openapi/primitive-functions-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-inbox-api
  name: Primitive Inbox API
  description: Check inbound email setup and processing readiness
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Inbox
  properties:
  - type: OpenAPI
    url: openapi/primitive-inbox-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-memories-api
  name: Primitive Memories API
  description: 'Durable org-scoped or function-scoped JSON key-value storage for

    agents and functions. Keys are caller-defined. Function scope is

    always addressed by the function id UUID, not by function name.'
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Memories
  properties:
  - type: OpenAPI
    url: openapi/primitive-memories-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-payments-api
  name: Primitive Payments API
  description: 'Collect and pay stablecoin (USDC) payments with x402. Settlement is

    non-custodial: funds move directly from payer to payee on-chain via an

    EIP-3009 authorization the payer signs with their own key, and Primitive

    never holds funds. The payee registers a payout address and creates a

    challenge; the payer signs and settles it under a configurable spend

    policy (kill-switch, per-payment and per-day caps, payee allowlist).'
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Payments
  properties:
  - type: OpenAPI
    url: openapi/primitive-payments-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-registries-api
  name: Primitive Registries API
  description: 'The Agent Registry: ownable directories of agents, addressable by a

    registry-scoped handle. A registry''s publish policy (owner_only, request,

    or open) decides whether a publish lists immediately or pends owner

    approval. An agent is defined once with a globally unique,

    reachability-verified address, then published into any registry under a

    handle. Discovery reads (list, resolve, get) are public for public

    registries; managing a registry and moderating requests use the owner''s

    API key.'
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Registries
  properties:
  - type: OpenAPI
    url: openapi/primitive-registries-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-routes-api
  name: Primitive Routes API
  description: 'Recipient routing: route inbound mail to a single destination per recipient

    address. Rules bind an address pattern (exact or wildcard) to an endpoint;

    `function_id` routes an address to a function, minting its route-target

    endpoint.'
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Routes
  properties:
  - type: OpenAPI
    url: openapi/primitive-routes-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-search-api
  name: Primitive Search API
  description: Semantic and hybrid search across received and sent mail
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Search
  properties:
  - type: OpenAPI
    url: openapi/primitive-search-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-sending-api
  name: Primitive Sending API
  description: Send outbound emails through the Primitive API
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Sending
  properties:
  - type: OpenAPI
    url: openapi/primitive-sending-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-service-api
  name: Primitive Service API
  description: Operational endpoints such as the unauthenticated health/liveness probe.
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Service
  properties:
  - type: OpenAPI
    url: openapi/primitive-service-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-templates-api
  name: Primitive Templates API
  description: Public Function template registry reads used to browse installable agent templates.
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Templates
  properties:
  - type: OpenAPI
    url: openapi/primitive-templates-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-threads-api
  name: Primitive Threads API
  description: Conversation threads spanning received and sent emails
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Threads
  properties:
  - type: OpenAPI
    url: openapi/primitive-threads-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-wake-api
  name: Primitive Wake API
  description: 'Wake scheduling: schedule and send typed wake commands to your own

    functions over real DKIM-signed email on a cron cadence, and manage the

    per-target allowlist that authorizes which senders may wake a function.'
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Wake
  properties:
  - type: OpenAPI
    url: openapi/primitive-wake-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
- aid: primitive:primitive-webhook-deliveries-api
  name: Primitive Webhook Deliveries API
  description: View and replay webhook delivery attempts
  humanURL: https://www.primitive.dev/docs/api
  baseURL: https://api.primitive.dev/v1
  tags:
  - Webhook Deliveries
  properties:
  - type: OpenAPI
    url: openapi/primitive-webhook-deliveries-api-openapi.yml
  - type: GraphQL
    url: graphql/primitive.graphql
common:
- type: DeveloperPortal
  url: https://www.primitive.dev/developers
- type: Documentation
  url: https://www.primitive.dev/docs
- type: APIReference
  url: https://www.primitive.dev/docs/api
- type: GettingStarted
  url: https://www.primitive.dev/docs/quickstart
- type: SignUp
  url: https://www.primitive.dev/signup
- type: Pricing
  url: https://www.primitive.dev/pricing
- type: Blog
  url: https://www.primitive.dev/blog
- type: Support
  url: https://www.primitive.dev/contact
- type: TermsOfService
  url: https://www.primitive.dev/terms
- type: PrivacyPolicy
  url: https://www.primitive.dev/privacy
- type: GitHubOrganization
  url: https://github.com/primitivedotdev
- type: Packages
  url: packages/primitive-packages.yml
- type: SDKs
  url: packages/primitive-packages.yml
- type: CLI
  url: cli/primitive-cli.yml
- type: MCPServer
  url: mcp/primitive-mcp.yml
- type: AgentSkill
  url: skills/_index.yml
- type: Sandbox
  url: sandbox/primitive-sandbox.yml
- type: LLMsTxt
  url: llms/primitive-llms.txt
- type: WellKnown
  url: well-known/primitive-well-known.yml
- type: SecurityTxt
  url: well-known/primitive-security.txt
- type: Authentication
  url: authentication/primitive-authentication.yml
- type: Conventions
  url: conventions/primitive-conventions.yml
- type: Idempotency
  url: conventions/primitive-conventions.yml
- type: ErrorCatalog
  url: errors/primitive-error-codes.yml
- type: Lifecycle
  url: lifecycle/primitive-lifecycle.yml
- type: Deprecation
  url: lifecycle/primitive-lifecycle.yml
- type: Webhooks
  url: asyncapi/primitive-webhooks.yml
- type: Components
  url: components/primitive-components.yml
- type: DataModel
  url: data-model/primitive-data-model.yml
- type: Conformance
  url: conformance/primitive-conformance.yml
- type: AgenticAccess
  url: agentic-access/primitive-agentic-access.yml
- type: Overlay
  url: overlays/primitive-openapi-overlay.yaml
- type: VulnerabilityDisclosure
  url: security/primitive-vulnerability-disclosure.yml
- type: Security
  url: security/primitive-vulnerability-disclosure.yml
- type: DomainSecurity
  url: security/primitive-domain-security.yml