Primitive SDKs

Primitive is an inbound and outbound email platform for building programmatic mail into agents and apps: you receive email as a normalized object, and you send, reply, or forward it back out through a typed client. Every SDK in this repository, Node.js, Python, and Go, plus the primitive CLI implement the identical version of that model, so the same mental model transfers no matter which language you use.

Unlike a raw SMTP/IMAP integration or a generic transactional-email API, Primitive treats an inbound email as a first-class, schema-validated webhook event and gives you one small verb set (receive, send, reply, forward) instead of a sprawling mailbox API to reimplement per project.

How it works#

1. 1

   An email arrives at your Primitive-managed inbox#

   Primitive receives the message over SMTP, evaluates SPF/DKIM/DMARC, and POSTs a signed email.received webhook event to your endpoint or Primitive Function.

2. 2

   Your handler verifies and normalizes the event#

   Call receive(...) (or the language equivalent) to verify the Primitive-Signature HMAC header and turn the raw event into a normalized email object with sender, replyTarget, subject, text, and thread fields. See the Inbound and Outbound Email Model for the full field reference.

3. 3

   You decide whether to trust the sender#

   Compute an email authenticity verdict from the auth results, then anchor it to an expected domain before taking any action that depends on who really sent the mail.

4. 4

   You reply, forward, or send fresh mail#

   client.reply(email, ...) threads a response automatically; client.forward(...) hands the message to someone else; client.send(...) starts a new thread. All three return as soon as Primitive accepts the message, unless you opt into wait mode for a delivery status.

5. 5

   Optionally, money moves in the same thread#

   The x402 payments model layers non-custodial USDC payments onto this same email flow: a payee creates a challenge, a payer signs it locally with their own wallet key, and Primitive settles on chain.

Get started#

Why Primitive#

• One verb set across three languages: receive/Receive, client.send/Send, client.reply/Reply, and client.forward/Forward behave identically in Node.js, Python, and Go, down to the same delivered / bounced / deferred / wait_timeout delivery-status vocabulary.
• Schema-validated webhooks, not guesswork: every email.received event is validated against a canonical JSON Schema before your handler ever sees it, and unknown future event types are preserved instead of rejected for forward compatibility.
• Built-in sender trust decisions: isTrustedSender/is_trusted_sender/IsTrustedSender anchors an SPF/DKIM/DMARC verdict to a specific domain, so you don't have to hand-roll header parsing to gate actions on "this really came from our domain."
• Non-custodial payments live in the same thread: the x402 payment model lets one agent request USDC and another pay it with a locally-signed EIP-3009 authorization, Primitive never holds funds, and a payment challenge can ride a real email thread instead of an out-of-band API call.
• A CLI for operator and deploy workflows: primitive (installable via npm install -g primitive) covers sending, replying, deploying Primitive Functions, managing recipient routing, and running the same x402 payment flows from your terminal or CI.

Technical details#

All three SDKs and the CLI are generated from the same OpenAPI spec and JSON Schema, which is why their method names, error shapes, and webhook contracts stay in lockstep across releases.