{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/what-is-primitive-3fcd5423","markdown_url":"https://test.abhinandan.one/what-is-primitive-3fcd5423.md","article":{"id":"ac93ce31-75a8-4bcf-8081-be9eb333da0d","article_slug":"what-is-primitive-3fcd5423","parent_article_slug":null,"parent_article_title":null,"kind":"overview","published_at":"2026-08-11T18:18:13.027104+00:00","keywords":["Primitive email API","receive reply forward send","primitive.receive","x402 USDC payments","email.received webhook event","primitive CLI"],"meta_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.","og_image_url":null,"source_file_paths":["README.md","docs/architecture.md"],"recording_id":null,"replayable":false,"task_name":"What is Primitive?","category":"Getting Started","summary":null,"description":"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.","content_kind":"repo_page","content_markdown":"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.\n\nUnlike 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.\n\n## How it works\n\n<Steps>\n\n<Step title=\"An email arrives at your Primitive-managed inbox\">\n\nPrimitive receives the message over SMTP, evaluates SPF/DKIM/DMARC, and POSTs a signed `email.received` webhook event to your endpoint or Primitive Function.\n\n</Step>\n\n<Step title=\"Your handler verifies and normalizes the event\">\n\nCall `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](email-model) for the full field reference.\n\n</Step>\n\n<Step title=\"You decide whether to trust the sender\">\n\nCompute an [email authenticity verdict](email-model) from the auth results, then anchor it to an expected domain before taking any action that depends on who really sent the mail.\n\n</Step>\n\n<Step title=\"You reply, forward, or send fresh mail\">\n\n`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](email-model) for a delivery status.\n\n</Step>\n\n<Step title=\"Optionally, money moves in the same thread\">\n\nThe [x402 payments](x402-payments-overview) 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.\n\n</Step>\n\n</Steps>\n\n## Get started\n\n<CardGroup cols={2}>\n\n<Card title=\"Try it in 5 minutes\" href=\"quickstart\">\n\nInstall an SDK or the CLI, set your API key, and receive, reply to, and send your first email.\n\n</Card>\n\n<Card title=\"Integrate with your stack\" href=\"node-sdk-quickstart\">\n\nWire up the Node.js SDK in a Next.js route handler, the flagship first-time integration path.\n\n</Card>\n\n<Card title=\"Using Python or Go instead?\" href=\"python-sdk-quickstart\">\n\nBoth SDKs implement the identical inbound/outbound model; pick by language, not by capability gap. See also the [Go SDK Quickstart](go-sdk-quickstart).\n\n</Card>\n\n<Card title=\"I'm an AI coding agent\" href=\"agent-guide\">\n\nA dense, single-page reference with install commands, canonical API shapes, and repo conventions to follow before opening a PR.\n\n</Card>\n\n</CardGroup>\n\n## Why Primitive\n\n- **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.\n- **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.\n- **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.\"\n- **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.\n- **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.\n\n## Technical details\n\n| Package | Install | Language runtime |\n|---|---|---|\n| Node.js SDK | `npm install @primitivedotdev/sdk` | Node.js 22+ |\n| Python SDK | `pip install primitivedotdev` | Python 3.10+ |\n| Go SDK | `go get github.com/primitivedotdev/sdks/sdk-go@latest` | Go 1.25+ |\n| CLI | `npm install -g primitive` | Node.js (separate package; `@primitivedotdev/sdk` no longer ships a `primitive` bin) |\n\nAll three SDKs and the CLI are generated from the same [OpenAPI spec and JSON Schema](monorepo-and-releases), which is why their method names, error shapes, and webhook contracts stay in lockstep across releases.","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/README.md","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+What+is+Primitive%3F&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fwhat-is-primitive-3fcd5423","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}