SDKs

Primitive publishes official SDKs for Node.js, Python, and Go. Use SDKs in application code and Functions. Use the CLI for terminal workflows; install it with Homebrew from primitivedotdev/tap or with npm as primitive (also published under the scoped name @primitivedotdev/cli).

Install

npm install @primitivedotdev/sdk
pnpm add @primitivedotdev/sdk
yarn add @primitivedotdev/sdk
bun add @primitivedotdev/sdk

pip install primitivedotdev
uv add primitivedotdev
poetry add primitivedotdev

go get github.com/primitivedotdev/sdks/sdk-go@latest

Receive an Email

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, {
    text: 'Got it.',
  });


  return Response.json({ ok: true });
}

import os
import primitive
from fastapi import FastAPI, Request


app = FastAPI()
client = primitive.client(api_key=os.environ['PRIMITIVE_API_KEY'])


@app.post('/webhooks/email')
async def handle(request: Request):
    body = await request.body()
    email = primitive.receive(
        body=body,
        headers=dict(request.headers),
        secret=os.environ['PRIMITIVE_WEBHOOK_SECRET'],
    )


    client.reply(email, {'text': 'Got it.'})
    return {'ok': True}

func handle(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    email, err := primitive.Receive(primitive.HandleWebhookOptions{
        Body:    body,
        Headers: r.Header,
        Secret:  os.Getenv("PRIMITIVE_WEBHOOK_SECRET"),
    })
    if err != nil {
        http.Error(w, "invalid signature", http.StatusForbidden)
        return
    }


    client, _ := primitive.NewClient(os.Getenv("PRIMITIVE_API_KEY"))
    client.Reply(context.Background(), email, primitive.ReplyParams{
        BodyText: "Got it.",
    })


    w.WriteHeader(http.StatusOK)
}

Reply helpers use reply-specific body keys: text and html in Node.js and Python, and BodyText and BodyHTML in Go. Send helpers use send-specific names such as bodyText in TypeScript.

Send an Email

const result = await client.send({
  from: 'support@yourdomain.com',
  to: 'alice@example.com',
  subject: 'Order confirmed',
  bodyText: 'Your order is on its way.',
  wait: true,
});


console.log(result.id, result.deliveryStatus);

result = client.send(
    from_email='support@yourdomain.com',
    to='alice@example.com',
    subject='Order confirmed',
    body_text='Your order is on its way.',
    wait=True,
)


print(result.id, result.delivery_status)

wait := true
result, err := client.Send(context.Background(), primitive.SendParams{
    From:     "support@yourdomain.com",
    To:       "alice@example.com",
    Subject:  "Order confirmed",
    BodyText: "Your order is on its way.",
    Wait:     &wait,
})

High-Level Helpers

The SDKs provide high-level helpers for:

• verifying and parsing inbound webhooks;
• sending new outbound messages;
• replying to an inbound email with threading derived from the parent;
• forwarding inbound context to a new recipient;
• verifying webhook signatures manually when you need lower-level control.

Functions Runtime Caveat

Hosted Primitive Functions execute JavaScript. Function handler examples are therefore TypeScript/JavaScript-only. Application code outside hosted Functions can use Node.js, Python, or Go SDKs.

Low-Level API Client

Inside hosted Functions, import the API-safe subpath:

import { createPrimitiveClient } from '@primitivedotdev/sdk/api';

The /api subpath avoids Node-only modules and is suitable for Workers-style runtimes.

Primitive Memories

Primitive Memories are durable JSON key-value records. In Node.js, use createPrimitiveClient().memories; org scope is the default, and function scope uses the function id UUID.

import { createPrimitiveClient } from '@primitivedotdev/sdk/api';


const client = createPrimitiveClient({
  apiKey: process.env.PRIMITIVE_API_KEY,
});


await client.memories.set({
  key: 'thread:latest',
  value: { email_id: 'em_123' },
});


const memory = await client.memories.get('thread:latest');


const page = await client.memories.search({
  prefix: 'thread:',
  includeValue: false,
});


await client.memories.delete('thread:latest');

Pass scope: { type: 'function', id: '<function-id>' } when setting a function-scoped memory. For get, delete, and search, pass scope_type=function&scope_id=<function-id>. Values must serialize as JSON. client.memories.search is key prefix search, not free-text or semantic search; use client.semanticSearch(...) for mail search.

See Primitive Memories for TTLs, version checks, metadata, search, and billing behavior.

x402 Payments

All three SDKs ship an x402 client for collecting and paying USDC non-custodially. Import the x402 client (in Node, @primitivedotdev/sdk/x402; in Python, primitive.x402; in Go, the primitive package's NewX402Client), register a payout address, create a challenge, and settle it with a locally-held key. See Collecting Payments for the full flow.

See CLI for terminal workflows.