{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/cli-inbox","markdown_url":"https://test.abhinandan.one/cli-inbox.md","article":{"id":"b69ab3f1-2e66-4834-9947-4ceeadb03bfc","article_slug":"cli-inbox","parent_article_slug":null,"parent_article_title":null,"kind":"guide","published_at":"2026-08-11T18:55:03.190559+00:00","keywords":["primitive inbox-setup","primitive inbox-status","receiving_ready","processing_ready","stored-only mode","actively_processed"],"meta_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.","og_image_url":null,"source_file_paths":["cli-node/src/oclif/commands/inbox-setup.ts"],"recording_id":null,"replayable":false,"task_name":"Inbox Setup and Status","category":"CLI","summary":null,"description":"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.","content_kind":"repo_page","content_markdown":"`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.\n\n`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.\n\n## What \"ready\" means\n\nPrimitive distinguishes two independent readiness states:\n\n- **Receiving ready**: at least one Primitive-managed domain can accept inbound mail.\n- **Processing ready**: an enabled endpoint or a deployed [Primitive Function](functions-and-routing-concepts) is actually wired up to handle it.\n\nA 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).\n\n<Note>\n\n`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.\n\n</Note>\n\n## Check and fix inbox readiness\n\n<Steps>\n\n<Step title=\"Run inbox-setup\">\n\n```bash\nprimitive inbox-setup\n```\n\nThis prints a readiness summary, the receive address on your first receiving-ready managed domain, a per-domain status table, and a processing-route count.\n\n</Step>\n\n<Step title=\"Read the mode line\">\n\nLook for one of three outcomes:\n\n```text\nMode: not receiving\n```\nNo managed domain is receiving-ready yet. Get a domain configured and receiving before anything else; re-run `primitive inbox-status` once you have.\n\n```text\nMode: stored-only\n```\nMail 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).\n\n```text\nMode: actively processed\n```\nInbound mail has an active processing route; nothing further is needed.\n\n</Step>\n\n<Step title=\"Follow the scaffold commands (stored-only mode only)\">\n\nWhen processing isn't active, `inbox-setup` prints the exact sequence to deploy a handler:\n\n```bash\nprimitive functions init inbound-reply\ncd inbound-reply\nnpm install\nnpm run build\nprimitive functions deploy --name inbound-reply --file ./dist/handler.js --wait\nprimitive functions test --id <function-id> --wait --show-sends\n```\n\nSubstitute the real function id (returned by `deploy`) for `<function-id>` in the `test` command. See [Primitive Functions: Deploy, Route, and Manage](cli-functions) for what each of these commands does.\n\n</Step>\n\n<Step title=\"Confirm the test call did something real\">\n\n`inbox-setup` lists what a successful `functions test --wait --show-sends` run should show you:\n\n- an inbound id for the generated test email\n- a function id matching the deployed Function\n- an invocation status of `completed`, `failed`, or `send_failed`\n- the reply/send result emitted by the handler\n\nIf any of those are missing, pull logs for the function:\n\n```bash\nprimitive functions logs --id <function-id>\n```\n\n</Step>\n\n<Step title=\"Re-check readiness\">\n\n```bash\nprimitive inbox-status\n```\n\nRe-run this after fixing anything; it's the fast, narrative-free version of step 1.\n\n</Step>\n\n</Steps>\n\n## Reading inbox-status directly\n\n`primitive inbox-status` returns the same underlying `InboxStatus` object `inbox-setup` narrates from, with per-domain and aggregate fields:\n\n```bash\nprimitive inbox-status\n```\n\nKey fields to script against:\n\n| Field | Meaning |\n|---|---|\n| `ready` | Overall readiness (receiving and processing both green) |\n| `receiving_ready` | At least one managed domain accepts inbound mail |\n| `processing_ready` | An enabled endpoint or deployed Function is wired up |\n| `domains[].managed` | Whether Primitive manages DNS for that domain |\n| `domains[].receiving_ready` | Per-domain receiving readiness |\n| `domains[].processing_ready` | Per-domain processing readiness |\n| `domains[].processing_route_count` | Count of [recipient routing](functions-and-routing-concepts) rules bound to that domain |\n| `endpoints.enabled` | Count of enabled webhook endpoints |\n| `functions.deployed` | Count of deployed Functions |\n| `next_actions` | API-suggested next commands, when present |\n\n<Tip>\n\nIf you manage DNS yourself instead of using a Primitive-managed domain, see [Managing Domains and Recipient Routes](cli-domains-and-routes) for the `domains-zone-file` command that generates the records you need.\n\n</Tip>\n\n<Warning>\n\n`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.\n\n</Warning>\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Primitive Functions: Deploy, Route, and Manage\" href=\"cli-functions\">\n\nScaffold, build, deploy, and test the handler that inbox-setup told you to create.\n\n</Card>\n\n<Card title=\"Managing Domains and Recipient Routes\" href=\"cli-domains-and-routes\">\n\nConfigure inbound domain DNS and bind recipient addresses to endpoints or functions.\n\n</Card>\n\n<Card title=\"Primitive Functions and Recipient Routing (Platform Concepts)\" href=\"functions-and-routing-concepts\">\n\nUnderstand how routes, endpoints, and Functions fit together to process inbound mail.\n\n</Card>\n\n<Card title=\"What is the Primitive CLI?\" href=\"cli-overview\">\n\nSee how inbox-setup fits into the CLI's broader command surface.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/cli-node/src/oclif/commands/inbox-setup.ts","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Inbox+Setup+and+Status&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fcli-inbox","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}