SDKs

Node.js, Python, and Go. High-level client for outbound and receive for inbound, plus lower-level webhook helpers and a typed REST client for advanced use.

Requirements

Node.js >=22

Installation

$npm install @primitivedotdev/sdk

Receive an email (high-level)

primitive.receive(...) verifies the signature, parses the body, validates the schema, and returns a normalized ReceivedEmail with the fields you actually use: sender, replyTarget, subject, text, attachments, thread.

import primitive from '@primitivedotdev/sdk';

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

export async function POST(req: Request) {
  // Verifies signature, parses JSON, validates schema, returns a normalized object.
  const email = await primitive.receive(req, {
    secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
  });

  console.log(email.sender.address); // {address, name?}
  console.log(email.subject);
  console.log(email.text);

  // Reply with derived recipient + threading
  await client.reply(email, 'Got it.');

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

Send, reply, forward (high-level)

client.send, client.reply, and client.forward cover the full outbound surface. See Sending mail for gates, idempotency, and threading.

const result = await client.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Order confirmed',
  bodyText: 'Your order is on its way.',
  wait: true,
});

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

// Forward an inbound message
await client.forward(email, {
  to: '[email protected]',
  bodyText: 'FYI, new bug report.',
});

Lower-level webhook helper (raw event shape)

const express = require('express');
const { handleWebhook, PrimitiveWebhookError } = require('@primitivedotdev/sdk');

const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/email', (req, res) => {
  try {
    const event = handleWebhook({
      body: req.body,
      headers: req.headers,
      secret: process.env.PRIMITIVE_WEBHOOK_SECRET,
    });

    console.log('Event:', event.id);
    console.log('Email from:', event.email.headers.from);
    console.log('Subject:', event.email.headers.subject);

    res.status(200).json({ received: true });
  } catch (error) {
    if (error instanceof PrimitiveWebhookError) {
      console.error(`[${error.code}] ${error.message}`);
      return res.status(400).json({ error: error.code });
    }

    throw error;
  }
});

app.listen(3000);

Features

handleWebhook() verifies signatures, parses JSON, and validates email.received.
parseWebhookEvent() keeps unknown future event types intact.
Return any 2xx HTTP response to acknowledge delivery.
Raw email helpers decode inline content and verify downloaded bytes.

Notes

The SDK accepts Request.headers directly in Fetch and Next.js handlers.

Node-only Extras

@primitivedotdev/sdk/contract builds and signs webhook payloads.
@primitivedotdev/sdk/parser parses raw .eml files and bundles attachments.

Typed REST client

For endpoints not covered by the high-level client, every SDK ships a generated, typed HTTP client for the full v1 surface:

Node: import { PrimitiveApiClient } from '@primitivedotdev/sdk/api'
Python: from primitive.api import create_client
Go: import primitiveapi "github.com/primitivedotdev/sdks/sdk-go/api"