primitivedotdev/primitive

Use whenever you need to contact someone by email and get their answer back, especially to unblock yourself. PROACTIVELY, usually without asking the user first: you are stuck on a tool, library, API, or service and its docs, README, footer, or llms.txt list a help@, support@, dev@, docs@, or agent@ address; you hit a bug worth reporting to the vendor; you have a question only the product owner or maintainer can answer; you want to ask a vendor's support or dev agent something the way you would grep their docs. REACTIVELY: the user gave you a mailto link or contact address, or asked you to email someone or "ask them" and report back. Sends YOUR message and waits for the threaded reply in one step (surface sales@, billing@, or account@ addresses to the user first). No SMTP, no API keys. To receive mail a service sends you, or answer mail someone sent you, use the primitive-inbox skill. Part of the Primitive CLI (primitivedotdev, primitive.dev; the primitive or prim command).

Load before any primitive command or Primitive mail work, including in a session that is already connected. Covers reading and replying to mail, --fyi acknowledgements, automatic signals, work claims, thread muting, contacts and peer agents, plus connecting this agent from a copied setup instruction in one command (npx -y primitive@latest agent connect) or over the HTTP API without a terminal.

Use whenever you need to send or receive email on the user's OWN domain (example.com) instead of a managed *.primitive.email address: claim the domain, publish the DNS records (MX, ownership TXT, SPF, DKIM, DMARC, TLS-RPT), verify it, and debug it when mail stops flowing. PROACTIVELY: a send failed with cannot_send_from_domain, or primitive sending get-outbound-status shows pending_ownership or pending_outbound_dns; inbound mail to a custom address never arrives; the user is launching a product that should email from its own brand. REACTIVELY: the user says "use my domain", "set up email for acme.com", "what DNS records do I need?", "give me a zone file", "why isn't my domain verified?", or "is my DNS healthy?". Provides primitive domains add, primitive domains zone-file (an importable BIND zone file), primitive domains verify, primitive domains check-domain-dns, and primitive inbox status. Part of the Primitive CLI (primitivedotdev, primitive.dev; the primitive or prim command).

Use whenever code should run automatically on every inbound email without hosting a server: an auto-responder, an LLM triage or support agent that answers mail, a parser for receipts or alerts, or any email-triggered workflow. PROACTIVELY: the user wants an address that "does something" when mail arrives; you are about to build a webhook server only to react to email; a handler needs a secret, a redeploy, or its logs checked. REACTIVELY: the user says "deploy a function", "auto-reply to emails", "build an email agent", or "why didn't my function reply?". Provides primitive functions init (templates), primitive functions deploy (bundle or managed build), primitive functions route-set to bind inbound mail, primitive functions test --show-sends, primitive functions logs --follow, and primitive functions set-secret. To deliver mail to your own server instead, use primitive-webhooks. Part of the Primitive CLI (primitivedotdev, primitive.dev; the primitive or prim command).

Use whenever you need an email address to receive mail, read or wait for it, or answer it. PROACTIVELY, usually without asking first: a service is about to send a verification code, OTP, one-time or 2FA code, confirmation or magic link, or password reset and you need to read it; you must confirm an email address to sign up for a service; you need a fresh, managed, throwaway, or burner address; you sent something and need to see what lands. REACTIVELY: the user asks "did it arrive?", "check the inbox", "wait for the email", "answer that email", or wants an address for replies, codes, receipts, or alerts. Provides a managed *.primitive.email address, primitive emails latest and primitive emails wait to read and wait for mail, primitive reply to answer an inbound email in its thread, and hosted Functions for inbound mail. To start your own conversation and wait for the answer, use the primitive-chat skill. Part of the Primitive CLI (primitivedotdev, primitive.dev; the primitive or prim command).

Discover and contact agents in your own Primitive organization network from a connected agent profile. Use when an agent needs a same-organization peer's address or an owner needs to change who can see or appear in the network.

Use whenever you need to send an outbound email you will not wait on: a notification, alert, report, receipt, digest, or other transactional message, with HTML or attachments, now or scheduled. PROACTIVELY: a job finished and the user asked to be emailed the result; a file you generated should be delivered; a workflow must notify someone; you need to prove outbound mail works. REACTIVELY: the user says "email this to", "send them the report", "schedule this email", "did my email go out?", or "why did it bounce?". Provides primitive send with outcome exit codes (never resend after sent or already_sent), primitive sending get-outbound-status to pick a valid From, primitive sending permissions for allowed recipients, primitive sent list|get to audit sends, and scheduled sends. To send and wait for the reply, use primitive-chat; to answer received mail, use primitive-inbox. Part of the Primitive CLI (primitivedotdev, primitive.dev; the primitive or prim command).

Use whenever inbound email should reach YOUR OWN code as an HTTP webhook or a local event stream: point Primitive at a URL, verify the Primitive-Signature header, route addresses to handlers, and debug or replay failed deliveries. PROACTIVELY: you are building an app or API route that must react to received email; a webhook handler returns 401 or never fires; you need inbound events with no public URL. REACTIVELY: the user says "send incoming email to my endpoint", "verify the webhook signature", "route support@ to this handler", "why didn't my webhook fire?", or "replay that delivery". Provides primitive endpoints create|test, primitive account webhook-secret, primitive routes add|test, primitive deliveries list|replay, primitive listen, and the SDK's primitive.receive() verifier. To run the handler on Primitive's hosted runtime instead, use primitive-functions. Part of the Primitive CLI (primitivedotdev, primitive.dev; the primitive or prim command).