{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/node-sdk-quickstart","markdown_url":"https://test.abhinandan.one/node-sdk-quickstart.md","article":{"id":"e6c3b319-e70e-42b8-96c2-1bf7200475c6","article_slug":"node-sdk-quickstart","parent_article_slug":null,"parent_article_title":null,"kind":"quickstart","published_at":"2026-08-11T18:55:01.578772+00:00","keywords":["@primitivedotdev/sdk","primitive.receive","primitive.client","PRIMITIVE_API_KEY","PRIMITIVE_WEBHOOK_SECRET","client.reply"],"meta_description":"Install @primitivedotdev/sdk, set PRIMITIVE_API_KEY, and receive and reply to an inbound email from a Next.js route handler in under 5 minutes.","og_image_url":null,"source_file_paths":["sdk-node/README.md"],"recording_id":null,"replayable":false,"task_name":"Node.js SDK Quickstart","category":"Node.js SDK","summary":null,"description":"Install @primitivedotdev/sdk, set your API key, and wire up a Next.js route that receives an inbound email and replies to it in under 5 minutes.","content_kind":"repo_page","content_markdown":"Get a Next.js route receiving and replying to real email in one pass: install `@primitivedotdev/sdk`, set your API key, and handle your first inbound webhook.\n\n<Note>\n\nRequires Node.js 22 or newer. You need a Primitive account and dashboard access to get an API key and a webhook secret.\n\n</Note>\n\n<Tip>\n\nBuilding in Python or Go instead? See the [Python SDK Quickstart](python-sdk-quickstart) or the [Go SDK Quickstart](go-sdk-quickstart). All three SDKs implement the identical inbound/outbound model, so pick by language, not by capability gap.\n\n</Tip>\n\n<Tip>\n\nJust need the CLI for your terminal or CI, not application code? Run `npm install -g primitive` instead; `@primitivedotdev/sdk` no longer ships a `primitive` bin. See [What is the Primitive CLI?](cli-overview)\n\n</Tip>\n\n<Steps>\n\n<Step title=\"Install the SDK\">\n\n```bash\nnpm install @primitivedotdev/sdk\n```\n\n</Step>\n\n<Step title=\"Set your API key and webhook secret\">\n\nGet an API key from your [dashboard](https://primitive.dev) and export it. The examples below read it from `process.env.PRIMITIVE_API_KEY`.\n\n```bash\nexport PRIMITIVE_API_KEY=prim_test\nexport PRIMITIVE_WEBHOOK_SECRET=whsec_...\n```\n\n`PRIMITIVE_API_KEY` authenticates outbound calls (`client.send`, `client.reply`, `client.forward`). `PRIMITIVE_WEBHOOK_SECRET` verifies that inbound webhook deliveries actually came from Primitive: `primitive.receive(...)` checks the `Primitive-Signature: t=<unix-seconds>,v1=<hex>` header against it automatically and rejects deliveries whose timestamp is more than 300 seconds old. See [Webhook Events Overview](webhook-events) for the full signature contract.\n\n</Step>\n\n<Step title=\"Receive and reply in a Next.js route\">\n\nCreate a route handler that receives an inbound email and replies to it:\n\n```ts\n// app/api/inbound/route.ts\nimport primitive from \"@primitivedotdev/sdk\";\n\nexport const runtime = \"nodejs\";\nexport const maxDuration = 300;\n\nconst client = primitive.client({\n  apiKey: process.env.PRIMITIVE_API_KEY!,\n});\n\nexport async function POST(req: Request) {\n  const email = await primitive.receive(req, {\n    secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,\n  });\n\n  await client.reply(email, \"Thank you for your email.\");\n\n  return Response.json({ ok: true });\n}\n```\n\n`primitive.receive(...)` reads the request body, verifies the HMAC-SHA256 signature against your webhook secret (rejecting expired or tampered deliveries), and returns a `ReceivedEmail`, the SDK-normalized representation of the inbound email. `client.reply(email, ...)` derives threading and the `Re:` subject from the parent message server-side, so no manual header wiring is required. See the [inbound and outbound email model](email-model) for the full object.\n\n</Step>\n\n<Step title=\"Point an inbound address at the route and verify\">\n\nConfigure a Primitive inbox or domain to deliver to this route's URL (see your dashboard for endpoint setup), then send a test email to that address.\n\nExpected result: the sender receives an automatic reply of \"Thank you for your email.\", and your route returns:\n\n```json\n{ \"ok\": true }\n```\n\nIf the route instead throws a `WebhookVerificationError`, check that `PRIMITIVE_WEBHOOK_SECRET` matches the secret shown in your dashboard and that you pass the raw `Request` object into `primitive.receive`. Verification runs over the exact request bytes, so a body that has already been parsed and re-serialized will not match.\n\n</Step>\n\n</Steps>\n\n## Send a new email instead of replying\n\nNot handling inbound mail yet? Send outbound mail directly with `client.send`:\n\n```ts\nimport primitive from \"@primitivedotdev/sdk\";\n\nconst client = primitive.client({\n  apiKey: process.env.PRIMITIVE_API_KEY!,\n});\n\nconst result = await client.send({\n  from: \"Support <support@example.com>\",\n  to: \"alice@example.com\",\n  subject: \"Hello\",\n  bodyText: \"Hi there\",\n});\n\nconsole.log(result.id, result.status, result.queueId);\n```\n\nBy default, `send` returns as soon as Primitive accepts the message for delivery. Pass `wait: true` (with `waitTimeoutMs`, default 30000) only when you need the first downstream SMTP outcome before responding. Full send/reply/forward behavior, attachments, and wait mode are covered in [Sending, Replying, and Forwarding Email](node-sdk-sending-email).\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"What is the Primitive Node.js SDK?\" href=\"node-sdk-overview\">\n\nSee how the package's subpath exports (root, webhook, api, x402) map to your use case.\n\n</Card>\n\n<Card title=\"Receiving Inbound Email\" href=\"node-sdk-receiving-email\">\n\nLearn every field available on the ReceivedEmail shape returned by primitive.receive.\n\n</Card>\n\n<Card title=\"Sending, Replying, and Forwarding Email\" href=\"node-sdk-sending-email\">\n\nControl threading, wait-for-delivery behavior, and attachments on send/reply/forward.\n\n</Card>\n\n<Card title=\"Node.js SDK Agent Guide\" href=\"node-sdk-agent-guide\">\n\nA dense single-page reference for AI coding agents wiring up this SDK.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/sdk-node/README.md","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Node.js+SDK+Quickstart&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fnode-sdk-quickstart","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}