Quickstart

Primitive is an inbound and outbound email API. This page gets you from a fresh install to a working receive-and-reply loop, using whichever SDK matches your stack, or the CLI if you'd rather work from the terminal.

You need a Primitive API key (prim_...) from your dashboard, and, if you're receiving inbound mail, a webhook secret (whsec_...) from the same account.

1. 1

   Install#

   Pick your language.

   Node.jsPythonGoCLI

   Requires Node.js 22 or newer.

   npm install @primitivedotdev/sdk
   

2. 2

   Set your API key#

   Get a key from your dashboard and export it as an environment variable. Every example on this page reads it from there.

   export PRIMITIVE_API_KEY=prim_test
   

   If you're receiving inbound mail, also export your webhook secret (used to verify the Primitive-Signature header):

   export PRIMITIVE_WEBHOOK_SECRET=whsec_...
   

   Tip

   Using the CLI instead? Skip the env var and authenticate interactively with primitive login, then confirm with primitive whoami. See Authentication: login, signup, logout, whoami for the full sign-in flow.

3. 3

   Receive and reply#

   This is the core loop every SDK is built around: normalize an inbound webhook into a ReceivedEmail, then reply to it. See the Inbound and Outbound Email Model for what's on that object and how reply threading works.

   Node.jsPythonGoCLI

   A Next.js route handler that receives inbound mail and replies:

   import primitive from "@primitivedotdev/sdk";
   
   export const runtime = "nodejs";
   export const maxDuration = 300;
   
   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 });
   }
   

   primitive.receive(...) reads the request body, verifies the HMAC-SHA256 signature against your account secret, and returns a normalized ReceivedEmail. client.reply(email, ...) derives threading and the Re: subject from the parent message server-side, you never set them yourself.

   Expected result: the handler returns {"ok": true} (Node) or its language equivalent, and the sender receives a reply threaded under the original message (same References, subject prefixed Re:).

4. 4

   Send a new email#

   Outbound mail that isn't a reply uses send instead. By default send returns as soon as Primitive accepts the message; pass wait: true to use wait mode and get the terminal SMTP delivery status before your handler returns.

   Node.jsPythonGoCLI

   import primitive from "@primitivedotdev/sdk";
   
   const client = primitive.client({
     apiKey: process.env.PRIMITIVE_API_KEY!,
   });
   
   const result = await client.send({
     from: "Support <support@example.com>",
     to: "alice@example.com",
     subject: "Hello",
     bodyText: "Hi there",
     wait: true,
     waitTimeoutMs: 5000,
   });
   
   console.log(result.id, result.status, result.queueId, result.deliveryStatus);
   

   Verify: check result.status / result.id in the response, or run primitive emails latest (CLI) / your inbox provider's sent-mail view to confirm delivery.

Escape hatches#

Next steps#