---
title: "Inbox Setup and Status"
canonical: "https://test.abhinandan.one/cli-inbox"
markdown_url: "https://test.abhinandan.one/cli-inbox.md"
publisher: "Primitive SDKs"
kind: "guide"
content_type: "reference"
category: "CLI"
description: "Use primitive inbox-setup to check whether inbound mail is receiving and processing, then follow its scaffold-deploy-test commands to wire up a Function."
keywords: ["primitive inbox-setup", "primitive inbox-status", "receiving_ready", "processing_ready", "stored-only mode", "actively_processed"]
last_modified: "2026-08-11T18:55:03.473083+00:00"
published_at: "2026-08-11T18:55:03.190559+00:00"
source_files:
  - "cli-node/src/oclif/commands/inbox-setup.ts"
sections:
  - {anchor: "what-ready-means", title: "What \"ready\" means"}
  - {anchor: "check-and-fix-inbox-readiness", title: "Check and fix inbox readiness"}
  - {anchor: "step-run-inbox-setup", title: "Run inbox-setup"}
  - {anchor: "step-read-the-mode-line", title: "Read the mode line"}
  - {anchor: "step-follow-the-scaffold-commands-stored-only-mode-only", title: "Follow the scaffold commands (stored-only mode only)"}
  - {anchor: "step-confirm-the-test-call-did-something-real", title: "Confirm the test call did something real"}
  - {anchor: "step-re-check-readiness", title: "Re-check readiness"}
  - {anchor: "reading-inbox-status-directly", title: "Reading inbox-status directly"}
  - {anchor: "next-steps", title: "Next steps"}
---

> Documentation index: https://test.abhinandan.one/llms.txt

# 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](https://test.abhinandan.one/functions-and-routing-concepts.md) 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

```bash
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:

```text
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.

```text
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).

```text
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:

```bash
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](https://test.abhinandan.one/cli-overview/cli-functions.md) 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:

```bash
primitive functions logs --id <function-id>
```

### 5. Re-check readiness

```bash
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:

```bash
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](https://test.abhinandan.one/functions-and-routing-concepts.md) 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](https://test.abhinandan.one/cli-overview/cli-domains-and-routes.md) 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.