Agent Guide

This page is a dense reference for AI coding agents integrating Primitive. It gives you install commands, canonical API shapes across all three SDKs and the CLI, codegen rules, and repo conventions. Read it instead of crawling every language-specific page.

Fastest successful path#

Full product model: What is Primitive?. Full onboarding walkthrough: Quickstart.

Install and authenticate#

npm install @primitivedotdev/sdk
export PRIMITIVE_API_KEY=prim_test
export PRIMITIVE_WEBHOOK_SECRET=whsec_...

pip install primitivedotdev
export PRIMITIVE_API_KEY=prim_test

go get github.com/primitivedotdev/sdks/sdk-go@latest
export PRIMITIVE_API_KEY=prim_test

npm install -g primitive
# or: npx primitive@latest <command>
primitive signin
primitive whoami

Canonical API shapes#

Receive, reply, send, forward: every SDK#

Full explanation of the normalized ReceivedEmail, wait mode, and delivery statuses: Inbound and Outbound Email Model. SDK-specific detail: Sending, Replying, and Forwarding Email (Node), Sending Email / Replying and Forwarding (Python), Sending Emails / Replying to Emails / Forwarding Emails (Go).

Node canonical snippet (the shape every quickstart converges on):

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, "Thank you for your email.");
  return Response.json({ ok: true });
}

Rules for every send/reply call:

• subject is never accepted on reply/Reply; a custom subject breaks Gmail's Conversation View threading. Use send/Send for full subject control.
• Default (no wait): returns as soon as Primitive accepts the message. Pass wait: true (Node), wait=True (Python), or a *bool pointing to true on Wait (Go) only when you need the terminal delivery status (delivered / bounced / deferred / wait_timeout) before responding. In that mode set a request timeout long enough for SMTP delivery, typically 30-60 seconds (waitTimeoutMs / wait_timeout_ms / WaitTimeoutMs defaults to 30000 ms and must be between 1000 and 30000).
• inbound_not_repliable (HTTP 422) means the inbound row cannot be replied to (rejected at ingestion, discarded content, or no recipient recorded).
• Idempotency: pass idempotencyKey / idempotency_key / IdempotencyKey on send/forward. Reusing a key replays the original response.

Webhook verification and event dispatch#

Signature wire format: header Primitive-Signature: t=<unix-seconds>,v1=<hex> (legacy MyMX-Signature mirrors the same value); signed string is ${timestamp}.${rawBody}; HMAC-SHA256 hex; secret from GET /account/webhook-secret used as raw UTF-8 (never base64-decode it); default tolerance 300 seconds. Event family discriminator is the X-Webhook-Event header, not a body field, full contract at Webhook Events Overview.

Event type catalog (identical across all SDKs):

email.received, email.bounced, email.tls_report, email.dmarc_report, email.dmarc_failure
payment.settled, payment.failed
interaction.x402.challenge, interaction.x402.payment, interaction.x402.settled,
interaction.x402.rejected, interaction.x402.declined, interaction.x402.expired,
interaction.x402.verify_timeout
interaction.ack.received, interaction.ack.requested, interaction.ack.acked,
interaction.ack.canceled, interaction.ack.expired

Email authenticity and sender trust#

validateEmailAuth's legit verdict does not say which domain authenticated: a fully authenticated email from any domain (including an attacker's) returns legit. Use the domain-anchored trust check for authorization decisions. Never gate on email.replyTarget / email.reply_target / email.ReplyTarget or the raw SMTP envelope sender; both are sender-controlled. Details: Verifying Inbound Email Authenticity.

x402 payments: every SDK#

Amounts: pass amountUsdc/amount_usdc/AmountUsdc as a human decimal string ("0.01"), the documented easy path. Set exactly one of that or amount/Amount in raw base units ("10000"; USDC has 6 decimals). Networks: base-sepolia (testnet, used in examples) or base (mainnet). Every method throws or returns X402Error carrying status (0 = the request may never have reached the server, so on pay() the outcome is indeterminate), body, and retryAfter. Full model: x402 Payments Overview.

CLI command surface#

Full command reference: What is the Primitive CLI?.

Generated API client (advanced surface)#

Use the high-level send/reply/receive surface for app code; drop to the generated client only for operations it doesn't cover (Memories, semantic search, account/domain management).

Reference: Generated API Client and Primitive Memories (Node), Generated API Client (Python).

Verification commands#

Run these after wiring an integration to confirm it works end to end.

# Node: typecheck + test suite
cd sdk-node && pnpm typecheck && pnpm test

# Python: dependency sync + tests + lint + typecheck
cd sdk-python && uv sync --dev && uv run pytest && uv run ruff check . && uv run basedpyright

# Go: unit tests + the cross-SDK shared compatibility fixtures
cd sdk-go && go test ./... && go test -run TestSharedCompatibilityFixtures ./...

# Repo root: run every SDK's checks through the shared task interface
make check
make shared-check

# CLI: confirm the packed build works and lists operations
primitive list-operations

The shared fixtures in test-fixtures/ pin behavioral parity across all three SDKs: schema validation outcomes, signature verification, auth classification, domain-anchored sender trust, raw-content helpers, and parseWebhookEvent/handleWebhook behavior. make shared-check runs the cross-SDK compatibility checks; in Go the suite is go test -run TestSharedCompatibilityFixtures ./.... If you touch webhook or auth logic in one SDK, run all three suites before committing.

Codegen rules (read before touching generated files)#

Change-strategy checklist when shared webhook behavior changes (from docs/architecture.md):

1. Update the canonical schema if the payload contract changed.
2. Regenerate language-specific artifacts.
3. Update test-fixtures/ when expected behavior changes.
4. Run make check.
5. Review each SDK for language-specific helper implications.

Release conventions (if your PR bumps a version)#

Do not hand-edit npm tokens into workflows; npm publishing uses trusted publishing/OIDC per RELEASE.md.

Pitfalls and do-not-use list#

• Do not base64-decode the webhook secret from GET /account/webhook-secret. It looks base64-shaped but must be used as a raw UTF-8 string for the HMAC key.
• Do not pass a custom subject to reply/Reply. The field is intentionally rejected or absent; use send/Send.
• Do not authorize actions based on email.sender/email.Sender, email.replyTarget/ReplyTarget, or the SMTP envelope mail_from. None are safe anchors; use the domain-anchored trust check.
• Do not treat an unknown auth verdict as always retryable. Check retryable explicitly: a domain with no DMARC record is a permanent unknown, not a transient one.
• Do not install @primitivedotdev/sdk expecting a primitive CLI bin. It no longer ships one; install the primitive package.
• Do not edit openapi/primitive-api.codegen.json or any file under a generated api/ directory. Edit the OpenAPI 3.1 source and regenerate.
• Do not use handleWebhook/handle_webhook/HandleWebhook if you need payment.* or interaction.* events. It is hard-typed to email.received; use the *WebhookEvent variant.
• Do not hand-set validBefore/valid_before/ValidBefore on an x402 signing call unless you have a specific reason. computePaymentValidityWindow clamps into the platform-accepted band (60s minimum settlement headroom, 24h maximum window) automatically.
• Do not send a private key over the network. Every x402 signer (PrivateKeySigner, viem LocalAccount) signs locally; only the signature and address ever leave the process.