Primitive SDKs (TypeScript, Python, Go)

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).

All three SDKs are open source in github.com/primitivedotdev/sdks and generated from the same OpenAPI spec.

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;
• deciding whether to trust an inbound email (validateEmailAuth for an overall SPF/DKIM/DMARC verdict, isTrustedSender to anchor that verdict to an expected From domain);
• 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:crypto (which the root and /webhook entries pull in), and its file attachment and payload helpers load node:fs lazily at call time instead of importing it, so Workers-style runtimes can bundle it without Node compatibility.

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.

See CLI for terminal workflows.