Back to Details

primitive-inbox

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

primitive-inbox

primitive-inbox

Give your agent a real inbox: a managed 
*.primitive.email
address that receives mail, plus the verbs to read it (
primitive emails latest
), wait for it (
primitive emails wait
), and run a handler on every message (
primitive functions deploy
). No SMTP, no DNS, no mail server to host.
为你的Agent提供一个真实的收件箱：一个可接收邮件的托管式
*.primitive.email
地址，以及用于读取邮件的
primitive emails latest
命令、等待邮件的
primitive emails wait
命令，还有用于为每封邮件运行处理程序的
primitive functions deploy
命令。无需SMTP、DNS，也无需自行托管邮件服务器。

When to reach for this

适用场景

Use freely (no user confirmation needed):
  • The user needs an address to receive replies, verification codes, alerts, or signups.
  • You sent a message and need to watch for the response.
  • You are building a workflow that reacts to inbound mail (parse it, trigger on it, route it).
  • You need a managed/throwaway address for a signup or an email verification.
Ask the user first:
  • Signing the address up for a third-party service, newsletter, or anything with side effects on a human.
  • Deploying a Function that auto-replies or takes action on inbound mail — confirm the behavior before it runs on real messages.
Use a different skill instead:
  • You need to send a message and get the reply — use primitive-chat (send + wait for the threaded answer).
可直接使用（无需用户确认）：
  • 用户需要一个地址来接收回复、验证码、通知或完成注册流程。
  • 你发送了消息，需要关注回复内容。
  • 你正在构建一个可响应收件邮件的工作流（解析邮件、触发操作、路由邮件）。
  • 你需要一个托管式/临时邮箱来完成注册或邮件验证。
需先询问用户：
  • 使用该地址注册第三方服务、订阅通讯或任何会对用户产生副作用的内容。
  • 部署可自动回复或对收件邮件执行操作的Function——在真实邮件上运行前需确认行为逻辑。
请使用其他技能：
  • 你需要发送消息并获取回复——请使用primitive-chat技能（发送消息并等待线程化回复）。

Setup

设置步骤

Install the CLI and provision a managed inbox. Signup is API-key-free: Primitive emails one 6-digit verification code to an address you choose, with no form and no human review.
bash
npm install -g @primitivedotdev/cli
Check for an existing account first with 
primitive account show
(or 
primitive whoami
). If it returns the user's account info, you are done. If it returns 
unauthorized
or a signed-out shape, offer to sign up right then.
Always ask the user explicitly which email to verify with before starting. Primitive emails the code to that address and the user reads it back. Do not default to an address from CLAUDE.md, memory, or project context.
bash
undefined
安装CLI并配置托管收件箱。注册无需API密钥：Primitive会向你选择的地址发送一个6位验证码，无需填写表单或人工审核。
bash
npm install -g @primitivedotdev/cli
请先检查是否已有账户，使用命令
primitive account show
（或
primitive whoami
）。如果返回用户的账户信息，则设置完成。如果返回
unauthorized
或未登录状态，请立即为用户注册。
开始注册前，请务必明确询问用户要用于验证的邮箱地址。Primitive会将验证码发送至该地址，用户需告知验证码内容。请勿默认使用CLAUDE.md、记忆或项目上下文里的地址。
bash
undefined

1. Start signup (ask which email FIRST, see above).

1. 开始注册（请先询问用户邮箱地址，见上文）。

primitive agent start-agent-signup --email <user-email> --terms-accepted
primitive agent start-agent-signup --email <user-email> --terms-accepted

Optional: add 
--signup-code <code>
ONLY if the user has already, unprompted, said they have one.

可选：仅当用户主动提及拥有注册码时，才添加
--signup-code <code>
参数。

2. Primitive emails a 6-digit verification code; the start output includes a signup-token.

2. Primitive会发送一个6位验证码；启动命令的输出包含一个signup-token。

Do not have the user paste the code into the chat. Read it through the shell so it

请勿让用户将验证码粘贴到聊天框中。请通过Shell读取验证码，

never enters your prompt:

确保验证码不会进入你的提示词：

read -rs CODE primitive agent verify-agent-signup --verification-code "$CODE" --signup-token <signup-token> unset CODE

**Two codes, do not confuse them.** The **signup code** (`--signup-code`) is an OPTIONAL invite/bonus code that the vast majority of users do not have: never prompt for it, and only pass it if the user volunteers one. The **verification code** is the REQUIRED 6-digit number Primitive emails to confirm the address; every signup gets one. If the user pastes the verification code into the chat anyway, use it once and do not echo it back. If a code "expired" or needs resending, it is the verification code: reissue it with `primitive agent resend-agent-signup-verification --signup-token <signup-token>` (do not re-run `start-agent-signup`, which begins a fresh session).

On success `verify-agent-signup` prints OAuth credentials; do not echo or relay that output. Confirm the result with `primitive whoami`, then find your managed `<random>.primitive.email` receive address and confirm inbound readiness:

```bash
primitive domains list    # shows the managed primitive.email domain assigned after verify
primitive inbox setup     # guided: shows your receive address and whether inbound is stored-only or actively processed
primitive inbox status    # consolidated inbound-readiness view
read -rs CODE primitive agent verify-agent-signup --verification-code "$CODE" --signup-token <signup-token> unset CODE

**注意区分两种验证码**。**注册码**（`--signup-code`）是可选的邀请/优惠码，绝大多数用户都没有：请勿主动索要，仅当用户主动提供时才使用。**验证码**是必填的6位数字，Primitive会发送该码以确认邮箱地址；所有注册流程都会生成此码。如果用户还是将验证码粘贴到了聊天框中，请使用一次，且不要将其回显。如果验证码“过期”或需要重新发送，请使用`primitive agent resend-agent-signup-verification --signup-token <signup-token>`重新发送验证码（请勿重新运行`start-agent-signup`，否则会开启新的会话）。

验证成功后，`verify-agent-signup`会输出OAuth凭据；请勿回显或转发该输出。使用`primitive whoami`确认结果，然后找到你的托管式`<random>.primitive.email`收件地址并确认收件就绪状态：

```bash
primitive domains list    # 显示验证后分配的托管primitive.email域名
primitive inbox setup     # 引导式操作：显示你的收件地址，以及收件邮件是仅存储还是会被主动处理
primitive inbox status    # 收件就绪状态的综合视图

How to use

使用方法

See the most recent inbound emails as a compact, TTY-aware table (
--json
returns the same envelope the API does, for parsing):
bash
primitive emails latest
primitive emails latest --json
Wait for a specific message to arrive, e.g. a reply or a verification code. Output is JSONL by default (
--table
for a human table); 
--timeout
is in seconds (
0
waits forever), 
--number/-n
exits after that many matches:
bash
primitive emails wait --to <your-address> --number 1 --timeout 120
primitive emails wait --subject verify --number 1 --timeout 120
primitive emails wait --q 'domain:example.com' --table
To run your own code on every inbound message (not just read it), deploy a Primitive Function and bind it to inbound mail. That is a separate, multi-step flow: 
functions init
, build the bundle, 
functions deploy --name <name> --file ./dist/handler.js
, then 
functions route-set --id <fn-id> --fallback
. Reading and waiting (above) needs none of that; reach for Functions only when you want a handler to execute on receipt.
以紧凑的、适配TTY的表格形式查看最新收件邮件（
--json
参数会返回与API相同的信封数据，用于解析）：
bash
primitive emails latest
primitive emails latest --json
等待特定邮件到达，例如回复或验证码。默认输出为JSONL格式（
--table
参数可生成适合人类阅读的表格）；
--timeout
参数单位为秒（
0
表示永久等待），
--number/-n
参数表示找到指定数量的匹配邮件后退出：
bash
primitive emails wait --to <your-address> --number 1 --timeout 120
primitive emails wait --subject verify --number 1 --timeout 120
primitive emails wait --q 'domain:example.com' --table
若要在每封收件邮件上运行自定义代码（而非仅读取邮件），请部署Primitive Function并将其绑定到收件邮件。这是一个独立的多步骤流程：
functions init
、构建包、
functions deploy --name <name> --file ./dist/handler.js
，然后执行
functions route-set --id <fn-id> --fallback
。上述的读取和等待操作无需这些步骤；仅当你需要在收到邮件时执行处理程序时，才使用Functions。

Why this exists

设计初衷

  • A real, managed receive address with no DNS to configure, no SMTP server, and no inbox to host yourself.
  • emails latest
    / 
    emails wait
    turn "did it arrive?" into a single agent-grade command (TTY-aware, 
    --json
    /JSONL for parsing).
  • It's the inbound half of agent email: to send a message and get the reply, pair with primitive-chat; to run code on each message, deploy a Function (see above).
  • 提供一个真实的托管式收件地址，无需配置DNS、SMTP服务器，也无需自行托管收件箱。
  • emails latest
    / 
    emails wait
    命令将“邮件到了吗？”这类需求转化为单个适用于Agent的命令（适配TTY，支持
    --json
    /JSONL格式用于解析）。
  • 它是Agent邮件功能的收件端：若要发送消息并获取回复，请搭配primitive-chat技能；若要在每封邮件上运行代码，请部署Function（见上文）。