Verified · 8/11/2026

Inbox Setup and Status

Run primitive inbox-setup for a readiness-aware guide to getting a managed inbox actually processing mail, and primitive inbox-status to inspect domain, endpoint, and function readiness at any time.

primitive inbox-setup tells you whether your Primitive inbox can currently receive mail, whether that mail is actively processed by a Function, and gives you the exact commands to close the gap. Run it any time you're not sure why inbound mail isn't reaching a handler, or right after claiming a domain to confirm it's ready.

primitive inbox-status is the underlying readiness data without the narrative: domain-by-domain and endpoint/function summaries, useful for scripting or a quick health check.

What "ready" means#

Primitive distinguishes two independent readiness states:

Receiving ready: at least one Primitive-managed domain can accept inbound mail.
Processing ready: an enabled endpoint or a deployed Primitive Function is actually wired up to handle it.

A domain can be receiving-ready but not processing-ready: mail arrives and is stored, but nothing acts on it. inbox-setup calls this stored-only mode, as distinct from actively processed (both ready) and not receiving (neither).

Note

inbox-setup builds its guide from the same inbox-status data that inbox-status prints directly, so the two commands never disagree. inbox-setup adds the readiness narrative and the next-action commands on top.

Check and fix inbox readiness#

1
Run inbox-setup#
```
primitive inbox-setup
```
This prints a readiness summary, the receive address on your first receiving-ready managed domain, a per-domain status table, and a processing-route count.
2
Read the mode line#
Look for one of three outcomes:
```
Mode: not receiving
```
No managed domain is receiving-ready yet. Get a domain configured and receiving before anything else; re-run primitive inbox-status once you have.
```
Mode: stored-only
```
Mail arrives and is stored, but no endpoint or Function is enabled to process it. inbox-setup prints the scaffold commands to fix this (next step).
```
Mode: actively processed
```
Inbound mail has an active processing route; nothing further is needed.
3
Follow the scaffold commands (stored-only mode only)#
When processing isn't active, inbox-setup prints the exact sequence to deploy a handler:
```
primitive functions init inbound-reply
cd inbound-reply
npm install
npm run build
primitive functions deploy --name inbound-reply --file ./dist/handler.js --wait
primitive functions test --id <function-id> --wait --show-sends
```
Substitute the real function id (returned by deploy) for <function-id> in the test command. See Primitive Functions: Deploy, Route, and Manage for what each of these commands does.
4
Confirm the test call did something real#
inbox-setup lists what a successful functions test --wait --show-sends run should show you:
- an inbound id for the generated test email
- a function id matching the deployed Function
- an invocation status of completed, failed, or send_failed
- the reply/send result emitted by the handler
If any of those are missing, pull logs for the function:
```
primitive functions logs --id <function-id>
```
5
Re-check readiness#
```
primitive inbox-status
```
Re-run this after fixing anything; it's the fast, narrative-free version of step 1.

Reading inbox-status directly#

primitive inbox-status returns the same underlying InboxStatus object inbox-setup narrates from, with per-domain and aggregate fields:

primitive inbox-status

Key fields to script against:

Field	Meaning
`ready`	Overall readiness (receiving and processing both green)
`receiving_ready`	At least one managed domain accepts inbound mail
`processing_ready`	An enabled endpoint or deployed Function is wired up
`domains[].managed`	Whether Primitive manages DNS for that domain
`domains[].receiving_ready`	Per-domain receiving readiness
`domains[].processing_ready`	Per-domain processing readiness
`domains[].processing_route_count`	Count of recipient routing rules bound to that domain
`endpoints.enabled`	Count of enabled webhook endpoints
`functions.deployed`	Count of deployed Functions
`next_actions`	API-suggested next commands, when present

Tip

If you manage DNS yourself instead of using a Primitive-managed domain, see Managing Domains and Recipient Routes for the domains-zone-file command that generates the records you need.

Warning

inbox-setup's scaffold commands assume a Primitive-managed domain is already receiving-ready. If your mode is not receiving, deploying a Function first won't help because mail can't reach it. Fix the domain state before scaffolding a handler.