Primitive

Name: Primitive
Author: Primitive

Primitive · io.pilot.primitive

Email for AI agents — provision a managed inbox in one call, then send, receive, reply, and search real email over one REST API.

Communications Live on catalogue

Install

pilotctl appstore install io.pilot.primitive

v1.0.0

Version

110

Methods

8.9 MB

Size

shareable

Sandbox

macOS · Linux

Platforms

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 send

10 / hour · 50 / day (free 'agent' plan)

API requests

60 / minute

Mailbox storage

1024 MB

Webhook endpoints

1 (global) on the free plan

Account creation

rate-limited per IP (429 after several new accounts/day) — signup is idempotent, so reuse the cached key

Recipient scope

reply-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.signup

Provision your own Primitive account and a managed *.primitive.email inbox in ONE call — no email, no code, no human step

primitive.get_account

Get account info

primitive.update_account

Update account settings

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

primitive.get_storage_stats

Get storage usage

primitive.get_webhook_secret

Get webhook signing secret

primitive.rotate_webhook_secret

Rotate webhook signing secret

primitive.list_domains

List all domains

primitive.update_domain

Update domain settings

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

primitive.delete_domain

Delete a domain

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

primitive.get_inbox_status

Get inbound inbox readiness

primitive.list_emails

List 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_emails

Search 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_email

Get inbound email by id

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

primitive.delete_email

Delete an email

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

primitive.download_raw_email

Download raw email

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

primitive.download_attachments

Download email attachments

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

primitive.reply_to_email

Reply 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_webhooks

Replay email webhooks

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

primitive.discard_email_content

Discard email content

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

primitive.get_conversation

Get the conversation an email belongs to

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

primitive.list_endpoints

List webhook endpoints

primitive.create_endpoint

Create 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_endpoint

Update a webhook endpoint

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

primitive.delete_endpoint

Delete a webhook endpoint

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

primitive.test_endpoint

Send a test webhook

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

primitive.list_filters

List filter rules

primitive.create_filter

Create a filter rule

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

primitive.update_filter

Update a filter rule

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

primitive.delete_filter

Delete a filter rule

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

primitive.list_deliveries

List webhook deliveries

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

primitive.replay_delivery

Replay a webhook delivery

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

primitive.get_send_permissions

List send-permission rules

primitive.send_email

Send 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_emails

List 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_email

Get a sent email by id

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

primitive.get_thread

Get a conversation thread by id

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

primitive.set_memory

Set 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_memory

Get a memory

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

primitive.delete_memory

Delete a memory

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

primitive.search_memories

Search 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_registries

List the registries you own

primitive.create_registry

Create a registry

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

primitive.get_registry

Get a public registry's metadata

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

primitive.update_registry

Update a registry you own

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

primitive.delete_registry

Delete a registry you own

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

primitive.list_registry_agents

List agents in a registry

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

primitive.publish_agent

Publish 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_handle

Resolve a registry handle to its agent

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

primitive.unpublish_agent

Unpublish an agent from a registry

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

primitive.list_registry_requests

List pending publication requests

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

primitive.decide_registry_request

Approve or reject a publication request

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

primitive.define_agent

Define an agent identity

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

primitive.get_agent

Get an agent's public profile by address

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

primitive.list_templates

List function templates

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

primitive.get_template

Get a function template

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

primitive.send_mail_batch

Send a batch of emails in one request

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

primitive.ask

Ask about Primitive — NLWeb query (no authentication)

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

primitive.get_health

Service health check

Requires an upgrade · 52

primitive.add_domain upgrade

Claim a new domain

requires 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_domain upgrade

Verify domain ownership

requires a custom domain whose DNS you control

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

primitive.download_domain_zone_file upgrade

Download domain DNS zone file

requires a custom domain whose DNS you control

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

primitive.list_wake_schedules upgrade

List wake schedules

requires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

primitive.create_wake_schedule upgrade

Create a wake schedule

requires 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_schedule upgrade

Get a wake schedule

requires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

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

primitive.update_wake_schedule upgrade

Update a wake schedule

requires 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_schedule upgrade

Delete a wake schedule

requires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

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

primitive.run_wake_schedule upgrade

Run a wake schedule now

requires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

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

primitive.list_wake_authorizations upgrade

List wake authorizations

requires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

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

primitive.create_wake_authorization upgrade

Create a wake authorization

requires 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_authorization upgrade

Update a wake authorization

requires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

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

primitive.delete_wake_authorization upgrade

Delete a wake authorization

requires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

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

primitive.list_wake_dispatches upgrade

List recent wake dispatches

requires a plan/entitlement upgrade — Wake scheduling is not on the free agent plan

example{"limit": 20}

primitive.list_routes upgrade

List recipient routes

requires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)

primitive.create_route upgrade

Create a recipient route

requires 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_routes upgrade

Reorder recipient routes

requires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)

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

primitive.simulate_route upgrade

Simulate routing for a recipient

requires 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_route upgrade

Update a recipient route

requires 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_route upgrade

Delete a recipient route

requires the recipient-routing feature — disabled on the free agent plan (the managed inbox routes to storage automatically)

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

primitive.semantic_search upgrade

Semantic search across received and sent mail

requires 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_functions upgrade

List functions