---
title: "What is Primitive?"
canonical: "https://test.abhinandan.one/what-is-primitive-3fcd5423"
markdown_url: "https://test.abhinandan.one/what-is-primitive-3fcd5423.md"
publisher: "Primitive SDKs"
kind: "overview"
content_type: "reference"
category: "Getting Started"
description: "Primitive is an inbound/outbound email platform with a normalized email object and receive/send/reply/forward methods shared across Node, Python, Go, and the CLI."
keywords: ["Primitive email API", "receive reply forward send", "primitive.receive", "x402 USDC payments", "email.received webhook event", "primitive CLI"]
last_modified: "2026-08-21T18:22:43.359885+00:00"
published_at: "2026-08-11T18:18:13.027104+00:00"
source_files:
  - "README.md"
  - "docs/architecture.md"
sections:
  - {anchor: "how-it-works", title: "How it works"}
  - {anchor: "step-an-email-arrives-at-your-primitive-managed-inbox", title: "An email arrives at your Primitive-managed inbox"}
  - {anchor: "step-your-handler-verifies-and-normalizes-the-event", title: "Your handler verifies and normalizes the event"}
  - {anchor: "step-you-decide-whether-to-trust-the-sender", title: "You decide whether to trust the sender"}
  - {anchor: "step-you-reply-forward-or-send-fresh-mail", title: "You reply, forward, or send fresh mail"}
  - {anchor: "step-optionally-money-moves-in-the-same-thread", title: "Optionally, money moves in the same thread"}
  - {anchor: "get-started", title: "Get started"}
  - {anchor: "why-primitive", title: "Why Primitive"}
  - {anchor: "technical-details", title: "Technical details"}
---

> Documentation index: https://test.abhinandan.one/llms.txt

# What is Primitive?

Primitive is an inbound and outbound email platform for AI agents, with Node.js, Python, and Go SDKs plus a CLI that all share the same receive/send/reply/forward model.

Primitive is an inbound and outbound email platform for building programmatic mail into agents and apps: you receive email as a normalized object, and you send, reply, or forward it back out through a typed client. Every SDK in this repository, Node.js, Python, and Go, plus the `primitive` CLI implement the identical version of that model, so the same mental model transfers no matter which language you use.

Unlike a raw SMTP/IMAP integration or a generic transactional-email API, Primitive treats an inbound email as a first-class, schema-validated webhook event and gives you one small verb set (`receive`, `send`, `reply`, `forward`) instead of a sprawling mailbox API to reimplement per project.

## How it works

### 1. An email arrives at your Primitive-managed inbox

Primitive receives the message over SMTP, evaluates SPF/DKIM/DMARC, and POSTs a signed `email.received` webhook event to your endpoint or Primitive Function.

### 2. Your handler verifies and normalizes the event

Call `receive(...)` (or the language equivalent) to verify the `Primitive-Signature` HMAC header and turn the raw event into a normalized email object with `sender`, `replyTarget`, `subject`, `text`, and `thread` fields. See the [Inbound and Outbound Email Model](https://test.abhinandan.one/email-model.md) for the full field reference.

### 3. You decide whether to trust the sender

Compute an [email authenticity verdict](https://test.abhinandan.one/email-model.md) from the auth results, then anchor it to an expected domain before taking any action that depends on who really sent the mail.

### 4. You reply, forward, or send fresh mail

`client.reply(email, ...)` threads a response automatically; `client.forward(...)` hands the message to someone else; `client.send(...)` starts a new thread. All three return as soon as Primitive accepts the message, unless you opt into [wait mode](https://test.abhinandan.one/email-model.md) for a delivery status.

### 5. Optionally, money moves in the same thread

The [x402 payments](https://test.abhinandan.one/x402-payments-overview.md) model layers non-custodial USDC payments onto this same email flow: a payee creates a challenge, a payer signs it locally with their own wallet key, and Primitive settles on chain.

## Get started

- [Try it in 5 minutes](https://test.abhinandan.one/quickstart.md): Install an SDK or the CLI, set your API key, and receive, reply to, and send your first email.

- [Integrate with your stack](https://test.abhinandan.one/node-sdk-quickstart.md): Wire up the Node.js SDK in a Next.js route handler, the flagship first-time integration path.

- [Using Python or Go instead?](https://test.abhinandan.one/python-sdk-quickstart.md): Both SDKs implement the identical inbound/outbound model; pick by language, not by capability gap. See also the [Go SDK Quickstart](https://test.abhinandan.one/go-sdk-quickstart.md).

- [I'm an AI coding agent](https://test.abhinandan.one/agent-guide.md): A dense, single-page reference with install commands, canonical API shapes, and repo conventions to follow before opening a PR.

## Why Primitive

- **One verb set across three languages**: `receive`/`Receive`, `client.send`/`Send`, `client.reply`/`Reply`, and `client.forward`/`Forward` behave identically in Node.js, Python, and Go, down to the same `delivered` / `bounced` / `deferred` / `wait_timeout` delivery-status vocabulary.
- **Schema-validated webhooks, not guesswork**: every `email.received` event is validated against a canonical JSON Schema before your handler ever sees it, and unknown future event types are preserved instead of rejected for forward compatibility.
- **Built-in sender trust decisions**: `isTrustedSender`/`is_trusted_sender`/`IsTrustedSender` anchors an SPF/DKIM/DMARC verdict to a specific domain, so you don't have to hand-roll header parsing to gate actions on "this really came from our domain."
- **Non-custodial payments live in the same thread**: the x402 payment model lets one agent request USDC and another pay it with a locally-signed EIP-3009 authorization, Primitive never holds funds, and a payment challenge can ride a real email thread instead of an out-of-band API call.
- **A CLI for operator and deploy workflows**: `primitive` (installable via `npm install -g primitive`) covers sending, replying, deploying Primitive Functions, managing recipient routing, and running the same x402 payment flows from your terminal or CI.

## Technical details

| Package | Install | Language runtime |
|---|---|---|
| Node.js SDK | `npm install @primitivedotdev/sdk` | Node.js 22+ |
| Python SDK | `pip install primitivedotdev` | Python 3.10+ |
| Go SDK | `go get github.com/primitivedotdev/sdks/sdk-go@latest` | Go 1.25+ |
| CLI | `npm install -g primitive` | Node.js (separate package; `@primitivedotdev/sdk` no longer ships a `primitive` bin) |

All three SDKs and the CLI are generated from the same [OpenAPI spec and JSON Schema](https://test.abhinandan.one/monorepo-and-releases.md), which is why their method names, error shapes, and webhook contracts stay in lockstep across releases.