Primitive

About Primitive

Primitive gives an agent a real, working email identity with no SMTP credentials, no DNS, and no human in the loop. primitive.signup provisions a free account plus a managed *.primitive.email inbox in one call (no email, no code). The adapter caches the API key locally under ~/.pilot and injects it on every subsequent call automatically — the agent never sees, stores, or passes it. Call signup once; everything else authenticates as you.

## What you can do on the free plan - Send outbound mail, reply on-thread, and batch-send, with attachments and idempotency keys. - Receive at your managed inbox: list, get, search, download raw MIME + attachments, and follow conversations. Long-poll for new mail with ?since=<cursor>&wait=30. - Filter inbound mail, register webhook endpoints, and read inbox readiness. - Primitive Memories — durable JSON key-value state across turns, retries, and inbound messages.

## Auth model One step: primitive.signup. It mints a prim_ API key + a provisioned inbox, caches both locally, and the key is injected on every call thereafter. Idempotent — a host that already has a key keeps it. Any method called before signup soft-fails with exact activation instructions instead of erroring.

## Requires an upgrade Four families are marked in primitive.help under a free-plan disclaimer: Functions (hosted JavaScript on inbound mail), Wake schedules, x402 USDC payments over email (invite-only), and custom Domains. They ship implemented and callable, and return a plan/entitlement error until the account is upgraded at primitive.dev.

Plan & limits

Outbound send10 / hour · 50 / day (free 'agent' plan)API requests60 / minuteMailbox storage1024 MBWebhook endpoints1 (global) on the free planAccount creationrate-limited per IP (429 after several new accounts/day) — signup is idempotent, so reuse the cached keyRecipient scopereply-only: send to other Primitive-managed addresses + anyone who has mailed you; upgrade for any recipient

Methods · 110

58 methods work on the free plan. The 52 below the divider need an account upgrade (paid plan, invite, or a verified custom domain).

primitive.signupProvision your own Primitive account and a managed *.primitive.email inbox in ONE call — no email, no code, no human stepprimitive.get_accountGet account infoprimitive.update_accountUpdate account settings

example{"spam_threshold": 10, "discard_content_on_webhook_confirmed": true}

primitive.get_storage_statsGet storage usageprimitive.get_webhook_secretGet webhook signing secretprimitive.rotate_webhook_secretRotate webhook signing secretprimitive.list_domainsList all domainsprimitive.update_domainUpdate domain settings

example{"id": "<id>", "is_active": true, "spam_threshold": 10}

primitive.delete_domainDelete a domain

example{"id": "<id>"}

primitive.get_inbox_statusGet inbound inbox readinessprimitive.list_emailsList inbound emails

example{"cursor": "<cursor>", "limit": 20, "domain_id": "<domain_id>", "status": "<status>", "search": "search terms", "date_from": "<date_from>", "date_to": "<date_to>"}

primitive.search_emailsSearch inbound emails

example{"q": "search terms", "from": "you@your-inbox.primitive.email", "to": "someone@example.com", "subject": "Subject line", "body": "<body>", "domain_id": "<domain_id>", "reply_to_sent_email_id": "<reply_to_sent_email_id>"}

primitive.get_emailGet inbound email by id

example{"id": "<id>"}

primitive.delete_emailDelete an email

example{"id": "<id>"}

primitive.download_raw_emailDownload raw email

example{"id": "<id>", "token": "<token>"}

primitive.download_attachmentsDownload email attachments

example{"id": "<id>", "token": "<token>"}

primitive.reply_to_emailReply to an inbound email

example{"id": "<id>", "body_text": "Plain-text body", "body_html": "<p>HTML body</p>", "from": "you@your-inbox.primitive.email", "wait": 30, "attachments": ["..."]}

primitive.replay_email_webhooksReplay email webhooks

example{"id": "<id>"}

primitive.discard_email_contentDiscard email content

example{"id": "<id>"}

primitive.get_conversationGet the conversation an email belongs to

example{"id": "<id>"}

primitive.list_endpointsList webhook endpointsprimitive.create_endpointCreate a webhook endpoint

example{"kind": "http", "url": "https://example.com/webhook", "function_id": "<function_id>", "enabled": true, "domain_id": "<domain_id>", "rules": {"...": "..."}, "is_route_target": true}

primitive.update_endpointUpdate a webhook endpoint

example{"id": "<id>", "url": "https://example.com/webhook", "enabled": true, "domain_id": "<domain_id>", "rules": {"...": "..."}}

primitive.delete_endpointDelete a webhook endpoint

example{"id": "<id>"}

primitive.test_endpointSend a test webhook

example{"id": "<id>"}

primitive.list_filtersList filter rulesprimitive.create_filterCreate a filter rule

example{"type": "whitelist", "pattern": "*@example.com", "domain_id": "<domain_id>"}

primitive.update_filterUpdate a filter rule

example{"id": "<id>", "enabled": true}

primitive.delete_filterDelete a filter rule

example{"id": "<id>"}

primitive.list_deliveriesList webhook deliveries

example{"cursor": "<cursor>", "limit": 20, "email_id": "<email_id>", "status": "<status>", "date_from": "<date_from>", "date_to": "<date_to>"}

primitive.replay_deliveryReplay a webhook delivery

example{"id": "<id>"}

primitive.get_send_permissionsList send-permission rulesprimitive.send_emailSend outbound email

example{"from": "you@your-inbox.primitive.email", "to": "someone@example.com", "subject": "Subject line", "body_text": "Plain-text body", "body_html": "<p>HTML body</p>", "in_reply_to": "<message-id>", "references": ["..."]}

primitive.list_sent_emailsList outbound sent emails

example{"cursor": "<cursor>", "limit": 20, "status": "<status>", "request_id": "<request_id>", "idempotency_key": "<idempotency_key>", "date_from": "<date_from>", "date_to": "<date_to>"}

primitive.get_sent_emailGet a sent email by id

example{"id": "<id>"}

primitive.get_threadGet a conversation thread by id

example{"id": "<id>"}

primitive.set_memorySet a memory

example{"key": "namespace/key", "value": {"any": "json"}, "scope": {"...": "..."}, "ttl_seconds": 10, "expires_at": "<expires_at>", "clear_ttl": true, "if_absent": true}

primitive.get_memoryGet a memory

example{"key": "namespace/key", "scope_type": "<scope_type>", "scope_id": "<scope_id>"}

primitive.delete_memoryDelete a memory

example{"key": "namespace/key", "scope_type": "<scope_type>", "scope_id": "<scope_id>", "if_version": "<if_version>"}

primitive.search_memoriesSearch memories

example{"prefix": "search terms", "cursor": "<cursor>", "limit": 20, "include_value": "<include_value>", "updated_after": "<updated_after>", "updated_before": "<updated_before>", "scope_type": "<scope_type>"}

primitive.list_registriesList the registries you ownprimitive.create_registryCreate a registry

example{"slug": "<slug>", "name": "<name>", "description": "<description>", "is_public": true, "publish_policy": "<publish_policy>"}

primitive.get_registryGet a public registry's metadata

example{"slug": "<slug>"}

primitive.update_registryUpdate a registry you own

example{"slug": "<slug>", "name": "<name>", "description": "<description>", "is_public": true, "publish_policy": "<publish_policy>"}

primitive.delete_registryDelete a registry you own

example{"slug": "<slug>"}

primitive.list_registry_agentsList agents in a registry

example{"slug": "<slug>", "limit": 20, "cursor": "<cursor>"}

primitive.publish_agentPublish an agent into a registry

example{"slug": "<slug>", "address": "someone@example.com", "handle": "<handle>", "display_name": "<display_name>", "endpoint_id": "<endpoint_id>", "title": "<title>", "description": "<description>"}

primitive.resolve_registry_handleResolve a registry handle to its agent

example{"slug": "<slug>", "handle": "<handle>"}

primitive.unpublish_agentUnpublish an agent from a registry

example{"slug": "<slug>", "handle": "<handle>"}

primitive.list_registry_requestsList pending publication requests

example{"slug": "<slug>", "limit": 20}

primitive.decide_registry_requestApprove or reject a publication request

example{"slug": "<slug>", "id": "<id>", "decision": "<decision>"}

primitive.define_agentDefine an agent identity

example{"address": "someone@example.com", "display_name": "<display_name>", "endpoint_id": "<endpoint_id>", "title": "<title>", "description": "<description>", "tags": ["..."]}

primitive.get_agentGet an agent's public profile by address

example{"address": "someone@example.com"}

primitive.list_templatesList function templates

example{"q": "search terms", "tag": "<tag>", "cursor": "<cursor>", "limit": 20}

primitive.get_templateGet a function template

example{"id": "<id>"}

primitive.send_mail_batchSend a batch of emails in one request

example{"messages": ["..."]}

primitive.askAsk about Primitive — NLWeb query (no authentication)

example{"q": "search terms", "prefer": {"...": "..."}}

primitive.get_healthService health checkRequires an upgrade · 52primitive.add_domainupgradeClaim a new domainrequires a custom domain whose DNS you control — the managed *.primitive.email inbox needs no domain setup

example{"domain": "<domain>", "confirmed": true, "outbound": true}

primitive.verify_domainupgradeVerify domain ownershiprequires a custom domain whose DNS you control

example{"id": "<id>"}

primitive.download_domain_zone_fileupgradeDownload domain DNS zone filerequires a custom domain whose DNS you control

example{"id": "<id>", "outbound_only": true}

primitive.list_wake_schedulesupgradeList wake schedulesrequires a plan/entitlement upgrade — Wake scheduling is not on the free agent planprimitive.create_wake_scheduleupgradeCreate a wake schedulerequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"from_address": "<from_address>", "target_address": "<target_address>", "command": "<command>", "cron_expr": "<cron_expr>", "args": {"...": "..."}, "timezone": "<timezone>", "note": "<note>"}

primitive.get_wake_scheduleupgradeGet a wake schedulerequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"id": "<id>"}

primitive.update_wake_scheduleupgradeUpdate a wake schedulerequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"id": "<id>", "enabled": true, "command": "<command>", "args": {"...": "..."}, "cron_expr": "<cron_expr>", "timezone": "<timezone>", "from_address": "<from_address>"}

primitive.delete_wake_scheduleupgradeDelete a wake schedulerequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"id": "<id>"}

primitive.run_wake_scheduleupgradeRun a wake schedule nowrequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"id": "<id>"}

primitive.list_wake_authorizationsupgradeList wake authorizationsrequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"recipient_endpoint_id": "<recipient_endpoint_id>"}

primitive.create_wake_authorizationupgradeCreate a wake authorizationrequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"recipient_endpoint_id": "<recipient_endpoint_id>", "allowed_sender_domain": "<allowed_sender_domain>", "allowed_sender_address": "<allowed_sender_address>", "allowed_commands": ["..."], "note": "<note>"}

primitive.update_wake_authorizationupgradeUpdate a wake authorizationrequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"id": "<id>", "enabled": true}

primitive.delete_wake_authorizationupgradeDelete a wake authorizationrequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"id": "<id>"}

primitive.list_wake_dispatchesupgradeList recent wake dispatchesrequires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"limit": 20}

primitive.list_routesupgradeList recipient routesrequires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)primitive.create_routeupgradeCreate a recipient routerequires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)

example{"match_type": "to", "pattern": "*@example.com", "endpoint_id": "<endpoint_id>", "function_id": "<function_id>", "domain_id": "<domain_id>", "priority": 0, "enabled": true}

primitive.reorder_routesupgradeReorder recipient routesrequires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)

example{"updates": ["..."]}

primitive.simulate_routeupgradeSimulate routing for a recipientrequires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)

example{"recipient": "someone@example.com", "event_type": "<event_type>"}

primitive.update_routeupgradeUpdate a recipient routerequires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)

example{"id": "<id>", "match_type": "to", "pattern": "*@example.com", "endpoint_id": "<endpoint_id>", "domain_id": "<domain_id>", "priority": 0, "enabled": true}

primitive.delete_routeupgradeDelete a recipient routerequires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)

example{"id": "<id>"}

primitive.semantic_searchupgradeSemantic search across received and sent mailrequires the Pro plan — semantic search over mail is not on the free agent plan

example{"query": "search terms", "mode": "<mode>", "corpus": ["..."], "search_in": ["..."], "exclude": ["..."], "date_from": "<date_from>", "date_to": "<date_to>"}

primitive.list_functionsupgradeList functionsrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent planprimitive.create_functionupgradeDeploy a functionrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"name": "<name>", "code": "<code>", "sourceMap": "<sourceMap>", "files": {"...": "..."}}

primitive.get_functionupgradeGet a functionrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>"}

primitive.update_functionupgradeUpdate and redeploy a functionrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>", "code": "<code>", "sourceMap": "<sourceMap>", "files": {"...": "..."}}

primitive.delete_functionupgradeDelete a functionrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>"}

primitive.test_functionupgradeSend a test invocationrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>", "local_part": "<local_part>"}

primitive.get_function_test_run_traceupgradeGet a function test run tracerequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>", "run_id": "<run_id>"}

primitive.get_org_routing_topologyupgradeGet the org's function routing topologyrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent planprimitive.get_function_routingupgradeGet a function's current route bindingrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>"}

primitive.set_function_routeupgradeBind a route to a functionrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>", "target": {"...": "..."}, "takeover": true}

primitive.unset_function_routeupgradeUnbind any route from a functionrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>"}

primitive.list_function_secretsupgradeList a function's secretsrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>"}

primitive.create_function_secretupgradeCreate or update a secretrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>", "key": "namespace/key", "value": {"any": "json"}}

primitive.set_function_secretupgradeSet a secret by keyrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>", "key": "namespace/key", "value": {"any": "json"}}

primitive.delete_function_secretupgradeDelete a secretrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>", "key": "namespace/key"}

primitive.list_org_secretsupgradeList org-level (global) secretsrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent planprimitive.create_org_secretupgradeCreate or update an org secretrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"key": "namespace/key", "value": {"any": "json"}}

primitive.set_org_secretupgradeSet an org secret by keyrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"key": "namespace/key", "value": {"any": "json"}}

primitive.delete_org_secretupgradeDelete an org secretrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"key": "namespace/key"}

primitive.list_function_logsupgradeList a function's execution logsrequires the developer plan — confirm an email at primitive.dev to upgrade; hosted Functions are not on the free agent plan

example{"id": "<id>", "limit": 20, "cursor": "<cursor>"}

primitive.register_payout_addressupgradeRegister a payout addressrequires the invite-only x402_payments + interactions_enabled entitlements

example{"address": "someone@example.com", "network": "<network>", "signature": "<signature>", "issued_at": "<issued_at>", "label": "<label>"}

primitive.list_payout_addressesupgradeList payout addressesrequires the invite-only x402_payments + interactions_enabled entitlementsprimitive.create_email_challengeupgradeCreate an email-native payment challengerequires the invite-only x402_payments + interactions_enabled entitlements

example{"from": "you@your-inbox.primitive.email", "to": "someone@example.com", "amount": "<amount>", "network": "<network>", "expires_in": 10, "resource": "<resource>", "description": "<description>"}

primitive.create_challengeupgradeCreate a payment challengerequires the invite-only x402_payments + interactions_enabled entitlements

example{"amount": "<amount>", "network": "<network>", "payer_org": "<payer_org>", "expires_in": 10, "resource": "<resource>", "description": "<description>"}

primitive.get_challengeupgradeGet a payment challengerequires the invite-only x402_payments + interactions_enabled entitlements

example{"id": "<id>"}

primitive.pay_challengeupgradePay a payment challengerequires the invite-only x402_payments + interactions_enabled entitlements

example{"id": "<id>", "payment": {"...": "..."}}

primitive.get_spend_policyupgradeGet your spend policyrequires the invite-only x402_payments + interactions_enabled entitlementsprimitive.update_spend_policyupgradeUpdate your spend policyrequires the invite-only x402_payments + interactions_enabled entitlements

example{"paused": true, "max_per_payment": "<max_per_payment>", "max_per_day": "<max_per_day>", "allowlist": ["..."]}

primitive.list_declined_paymentsupgradeList declined paymentsrequires the invite-only x402_payments + interactions_enabled entitlementsprimitive.install_templateupgradeInstall a function templaterequires the developer plan — installs a template as a hosted Function

example{"id": "<id>", "address": "someone@example.com", "domain": "<domain>", "variables": {"...": "..."}, "secrets": {"...": "..."}}

primitive.get_template_installupgradeGet template install statusrequires the developer plan — tracks a hosted Function install

example{"id": "<id>"}

What’s New

v1.0.0Latest—

• Initial release — Primitive's email API for agents over one byo HTTPS app: 110 methods + primitive.help.
• Emailless one-call signup (primitive.signup): mints a prim_ API key + a managed *.primitive.email inbox with no email or code; the key is cached locally and injected on every call automatically.
• Full email lifecycle on the free plan: send/reply/batch, inbound list/get/search/raw/attachments/conversations, threads, filters, webhook endpoints, and durable Memories.
• Functions, Wake schedules, x402 payments, and custom domains are implemented and marked gated until the account is upgraded.

Platform Compatibility

macOSApple Silicon4.6 MBSupportedmacOSIntel5.0 MBSupportedLinuxarm644.8 MBSupportedLinuxamd645.2 MBSupported