Primitive SDKs
Monorepo for the Primitive SDKs.
Primitive is an inbound and outbound email platform. The SDKs are centered on a
small default workflow:
- receive an inbound email
- inspect a normalized email object
- send, reply, or forward synchronously
SDKs
| SDK | Install target | README |
|---|
| Node.js | npm install @primitivedotdev/sdk | sdk-node/README.md |
| Python | pip install primitivedotdev | sdk-python/README.md |
| Go | go get github.com/primitivedotdev/sdks/sdk-go/v2@latest | sdk-go/README.md |
Default API shape
Across the SDKs, the default story is:
- receive inbound mail with
receive(...)
- create an outbound client with
client(...)
- send new mail with
send(...)
- continue a thread with
reply(...)
- forward a message with
forward(...)
The Node.js end-state looks like this:
import primitive from "@primitivedotdev/sdk";
const client = primitive.client({
apiKey: process.env.PRIMITIVE_API_KEY!,
});
export async function POST(req: Request) {
const email = await primitive.receive(req, {
secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
});
await client.reply(email, "Thank you for your email.");
return Response.json({ ok: true });
}
x402 payments
Each SDK also ships a non-custodial x402 payments client. One agent registers a
payout address and requests a USDC payment; the paying agent signs locally with
its own key and settles. Keys never leave the caller. Networks are base and
base-sepolia, and amounts are token base units (USDC has 6 decimals, so
"10000" is 0.01 USDC). See the "x402 payments" section in each SDK README
(sdk-node, sdk-python, sdk-go) for runnable examples, and the
primitive payments command group in the CLI for the same flow from a terminal.
Advanced surfaces
The low-level and generated APIs still exist for advanced use cases:
- webhook verification/parsing helpers
- generated HTTP API packages
- Primitive Memories key-value operations
- OpenAPI exports
- contract tooling
- raw MIME parsing helpers
- CLI
The SDK refresh keeps those escape hatches available, but the primary docs story
focuses on the inbound/outbound automation flow above.
Repository layout
sdks/
.github/workflows/
openapi/
json-schema/
sdk-go/
sdk-node/
sdk-python/
test-fixtures/
Development
Use the root Makefile as the main task interface:
make node-generate python-generate go-generate
make check
make build
make shared-check
The Makefile wraps each SDK's native commands. You can still run them directly
from each SDK directory when needed:
cd sdk-node && pnpm typecheck && pnpm test
cd sdk-python && uv sync --dev && uv run pytest && uv run ruff check . && uv run basedpyright
cd sdk-go && go test ./... && go test -run TestSharedCompatibilityFixtures ./...
Documentation
docs/architecture.md gives the repository architecture and package layoutdocs/schema-generation.md documents schema/codegen flowdocs/repo-model.md documents the monorepo task modelRELEASE.md documents the release process
Primitive developer resources
Everything for building on primitive.dev, the email API for AI agents:
