---
title: "Sending, Replying, and Searching Email from the CLI"
canonical: "https://test.abhinandan.one/cli-overview/cli-email-commands"
markdown_url: "https://test.abhinandan.one/cli-overview/cli-email-commands.md"
publisher: "Primitive SDKs"
kind: "guide"
content_type: "reference"
category: "CLI"
parent: "cli-overview"
description: "Send mail with primitive send --wait, reply with primitive reply --id, and run keyword or semantic search from the terminal."
keywords: ["primitive send", "primitive reply", "primitive emails latest", "primitive search", "primitive semantic-search", "primitive emails watch"]
last_modified: "2026-08-11T18:54:52.474292+00:00"
published_at: "2026-08-11T18:54:52.309658+00:00"
source_files:
  - "cli-node/src/oclif/commands/inbox-setup.ts"
  - "cli-node/src/oclif/commands/inbox-status.ts"
sections:
  - {anchor: "send-a-new-email", title: "Send a new email"}
  - {anchor: "step-send-with-wait-mode", title: "Send with wait mode"}
  - {anchor: "step-read-the-delivery-status", title: "Read the delivery status"}
  - {anchor: "reply-to-an-inbound-email", title: "Reply to an inbound email"}
  - {anchor: "forward-an-inbound-email", title: "Forward an inbound email"}
  - {anchor: "list-and-inspect-emails", title: "List and inspect emails"}
  - {anchor: "view-the-latest-messages", title: "View the latest messages"}
  - {anchor: "poll-an-inbox", title: "Poll an inbox"}
  - {anchor: "search-email", title: "Search email"}
  - {anchor: "verify-your-inbox-is-set-up-to-receive-mail", title: "Verify your inbox is set up to receive mail"}
  - {anchor: "next-steps", title: "Next steps"}
---

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

# Sending, Replying, and Searching Email from the CLI

Send, reply to, and search email straight from the terminal with the primitive CLI, using the same wait-mode delivery semantics and search model as the SDKs.

Use these commands when you want to send, reply to, or inspect mail without leaving the terminal, for one-off testing, CI smoke checks, or scripting an agent workflow around the [CLI](https://test.abhinandan.one/cli-overview.md). All of them wrap the same high-level `send`/`reply`/`forward` flow documented in [Inbound and Outbound Email Model](https://test.abhinandan.one/email-model.md); the CLI just gives you flags instead of SDK calls.

> **Note:** Every command below needs an authenticated CLI session or an API key. See [Authentication: login, signup, logout, whoami](https://test.abhinandan.one/cli-overview/cli-authentication.md) if you haven't run `primitive login` yet.

## Send a new email

`primitive send` posts a new outbound message; `--to` and `--body` are enough for a minimal send.

```bash
primitive send --to alice@example.com --body "Hello!"
```

Run `primitive send --help` for the full flag list in your installed version. Add `--wait` to hold the command open until the first downstream SMTP delivery outcome instead of returning as soon as Primitive accepts the message, the same [wait mode](https://test.abhinandan.one/email-model.md) the SDKs expose as `wait: true`:

### 1. Send with wait mode

```bash
primitive send --to alice@example.com --body "Hello!" --wait
```

### 2. Read the delivery status

The JSON response includes a `delivery_status` field: `delivered`, `bounced`, `deferred`, or `wait_timeout`. Treat `wait_timeout` as "outcome unknown", the send may still complete after the command returns.

## Reply to an inbound email

`primitive reply --id <inbound-email-id> --body "..."` replies to a specific inbound message. Recipients, subject (`Re: ...`), and threading headers are derived server-side from the inbound row, matching every SDK's `reply()` behavior. A custom subject is not supported, because Gmail's Conversation View needs a normalized-subject match in addition to a References match, so overriding the subject silently breaks threading for half the recipient population.

```bash
primitive reply --id <inbound-email-id> --body "Thanks for reaching out."
```

Attach a file with `--attachment`:

```bash
primitive reply --id <inbound-email-id> --body "See attached" --attachment ./report.pdf
```

The interactive REPL form, `primitive chat reply "..." --attachment ./report.pdf`, works the same way inside a chat session. See [Memories and Chat Commands](https://test.abhinandan.one/cli-overview/cli-memories-and-chat.md).

> **Warning:** If the inbound row isn't in a repliable state (rejected at ingestion, content discarded, or no recipient recorded), the API returns `inbound_not_repliable` (HTTP 422) and the CLI exits non-zero. Retrying will not help; the original inbound message has to be resent. A missing `Message-Id` does not block the reply, it only omits the threading headers.

## Forward an inbound email

The CLI has no dedicated forward command. Forwarding in the SDKs is a `send` with a generated "Forwarded message" body, so from the terminal you compose the same thing with `primitive send`, or drive the API directly through the generic operation shortcut described in [Direct API Access and Generic Commands](https://test.abhinandan.one/cli-overview/cli-generic-api-access.md). Run `primitive list-operations` to see every operation available in your installed version.

## List and inspect emails

`primitive emails list` lists inbound mail; `primitive emails get --id <inbound-email-id>` fetches one. `primitive sent list` lists outbound mail the same way.

```bash
primitive emails list
primitive emails get --id <inbound-email-id>
primitive sent list
```

### View the latest messages

```bash
primitive emails latest --limit 5
```

### Poll an inbox

Run `primitive emails --help` for the polling and watch subcommands available in your installed version, along with their poll-interval and filter flags.

## Search email

Two search modes are available, matching the generated `search` and `semantic-search` operations:

- **`primitive search`**, keyword search across received and sent mail.
- **`primitive semantic-search`**, ranked semantic/hybrid/keyword search with match excerpts and a score breakdown. Requires the Pro plan and the `semantic_search_enabled` entitlement; without them the API returns a 403.

```bash
primitive search --help
primitive semantic-search --help
```

> **Tip:** Semantic search concepts (modes, corpus selection, scoring) are shared across every SDK and the CLI, and each ranked row carries matched fields, a match-centered excerpt, and an additive score breakdown. See [Semantic Search](https://test.abhinandan.one/go-semantic-search.md) for the shared parameter reference.

## Verify your inbox is set up to receive mail

Before you can reply to anything, inbound mail has to actually reach an endpoint or Function. `primitive inbox-status` reports readiness without side effects: it fetches the server-owned inbox status, shows the first usable receive address on a Primitive-managed domain, and tells you whether inbound mail is stored-only or actively processed by a route.

```bash
primitive inbox-status
```

Output includes:

- **Readiness**: whether the account overall is `ready`, plus separate `receiving_ready` / `processing_ready` flags.
- **Receive address**: the first receiving-ready, active, Primitive-managed domain, formatted as `inbox@<domain>`.
- **Mode**: `actively_processed` (a route is bound), `stored_only` (mail arrives but nothing processes it), or `not_receiving`.
- **Domains**: per-domain status, receive/process readiness, and route count.

Run `primitive inbox-setup` for the same readiness data plus copy-pasteable next steps, the exact `primitive functions init`, `deploy --wait`, and `functions test --id <function-id> --wait --show-sends` commands to scaffold and wire up a processing Function when none is bound yet:

```bash
primitive inbox-setup
```

> **Note:** `inbox-setup` never deploys anything itself; it only prints the commands. Follow the printed scaffold steps (or see [Primitive Functions: Deploy, Route, and Manage](https://test.abhinandan.one/cli-overview/cli-functions.md)) to actually wire up a processing route.