Skip to content
Extrovert Extrovert Docs

Zero to first email

Start with Set up your agent for the shortest installation path, including connecting an existing account with limited access. This page explains the first-email workflow and the lower-level enrollment alternative.

After your first practice message is reviewed and sent, you can optionally enable Skip review for emails to you in Review -> Auto-send. It starts off so you can practice giving feedback and teaching a writing rule. It only skips review when your verified email is the sole To recipient, with no Cc/Bcc or aliases; writing rules and other recipients’ usual review requirements remain unchanged. See the exact scope and reminder options.

Paste this into your agent:

Read https://docs.extrovert.dev/llms.txt and follow its setup checklist in order to send my first email. Stop and report install errors. Do not request credentials in chat.

Already installed? Use the update prompt to refresh your existing setup, including older installations.

The agent reads current guidance using agent_context or the public update check before choosing a connection path.

For an interactive assistant, connect hosted MCP, choose its access, and call whoami and list_inboxes. Use an existing inbox when that is your task. Creating a new inbox needs project or organization reach and create permission; selected-inbox access excludes future inboxes. Full control also permits setup.

For a local terminal or stdio MCP host, use existing-account CLI login, then verify whoami. SSH and non-interactive agents can complete that same login through the hosted page.

If skill installation fails in the intended host, stop setup and report the error. For a host-protected path, request host approval or ask the person to run the same installer command in their terminal. Preserve the native path and its protections. Resume after installation succeeds; a later successful login does not repair it. If browser consent or the host restart is unfinished, report setup as pending with the next action. Verify whoami through the resumed MCP connection before calling its tools available; saved configuration or local CLI identity alone does not establish that connection.

The steps below use an enrollment key for a new deployed agent. Skip enrollment if already connected. You will create an inbox, submit mail for review, wait for a reply, and answer in the same thread. For a new account, check current signup availability before using the optional path below.

1. Redeem an enrollment key

Section titled “1. Redeem an enrollment key”

In the console, open Credentials > Enrollment keys and issue a key when setup needs to create the agent. Select only the permissions the agent needs. For this guide, include mailbox:create, mailbox:read, and mailbox:send.

Terminal window
npx -y @extrovert.dev/mcp enroll --agent-handle support-agent
npx -y @extrovert.dev/mcp whoami

Paste the enrollment key at the hidden prompt. The CLI saves the agent key privately; it does not print it. Use EXTROVERT_PROFILE before enrollment to keep different agents’ credentials separate.

2. Create an inbox

Section titled “2. Create an inbox”

Omit username and domain to create an @extrovertmail.com address on a paid account. Use a stable client_id or Idempotency-Key when retrying after a transport timeout.

Terminal window
curl -sS -X POST "$EXTROVERT_API_BASE_URL/v1/inboxes" \
  -H "Authorization: Bearer $EXTROVERT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-agent-primary" \
  -d '{ "display_name": "Support agent" }'

3. Read the review policy

Section titled “3. Read the review policy”

Call GET /v1/inboxes/{inbox_id}, extrovert.inboxes.get(id), or get_inbox before the first send. The single-inbox response includes effective_review_policy.

New accounts use require_review. Under that policy, every send, reply, and forward needs an intent.summary. Without it, the API returns 422 intent_required; nothing is sent or queued.

4. Submit a message

Section titled “4. Submit a message”
Terminal window
curl -sS -X POST \
  "$EXTROVERT_API_BASE_URL/v1/inboxes/$INBOX_ID/send" \
  -H "Authorization: Bearer $EXTROVERT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: notify-ops-001" \
  -d '{
    "to": ["ops@acme.test"],
    "subject": "Support inbox ready",
    "text": "The support inbox is ready.",
    "intent": { "summary": "Tell operations that the support inbox is ready" }
  }'

The normal response under require_review is:

{
  "kind": "queued_for_review",
  "review": { "id": "rr_8Tz4kP", "state": "needs_review", "effective_mode": "review" }
}

The message has not been delivered. Wait for a terminal review event or poll GET /v1/reviews/rr_8Tz4kP until closed is true.

5. Wait for a reply

Section titled “5. Wait for a reply”

After the review reaches sent, wait for new mail:

wait.ts
const result = await inbox.waitForEmail({
  from: "ops@acme.test",
  timeout_seconds: 120,
});


if (result.timed_out) throw new Error("No reply arrived in time");

wait_for_email returns the canonical message fields. It also returns an extracted OTP code and verification link when present. See Messages, threads, and search for the difference between source text and html fields and their best-effort extracted variants.

6. Reply in the same thread

Section titled “6. Reply in the same thread”

Reference the returned message_id. The server derives recipients and threading headers. Reply follows the same review policy as send.

reply.ts
await inbox.reply({
  message_id: result.message!.id,
  text: "Thanks. I will keep this address monitored.",
  intent: { summary: "Acknowledge the reply and confirm the inbox remains monitored" },
  idempotency_key: "reply-ops-001",
});

Optional self-signup path

Section titled “Optional self-signup path”

Check GET /v1/signup-status before offering free self-signup. When incoming-email activation is available, sign_up returns activation_method: incoming_email and reserves the inbox for 24 hours. Ask the human to send an email from the returned human_email to the returned address; any subject or body works. No verification email is sent to the human. Call check_activation, then verify_signup without an OTP only after activation is proven to exchange the temporary key for a durable key. Check whoami before mailbox work. Pending keys cannot read or send mail. See the activation steps for correction, console approval, and legacy OTP compatibility.

Use an existing account first. Unattended workers must receive the human email through authorized setup; never invent an address or bypass verification. Retain pending state until the human completes activation.

If a legacy signup response actually issued an OTP and that email is missing, confirm its destination and suggest Spam or Junk. Identify the sender from that response, not a guessed no-reply address. Use the human-supplied code before its original expiry; this recovery advice does not apply to incoming-email activation.

Your first conversation with your agent

Section titled “Your first conversation with your agent”

Choose a sender name during signup with display_name, for example Coleman. This is the name people see beside the email address; username chooses the address itself. Omitting the sender name uses the validated Agent {username} default. You can change it later with update_inbox. The same sender-name validation applies to signup and inbox creation.

After you send the activation email, your connected agent can watch with check_activation {"wait_seconds":55}. Each wait lasts at most 55 seconds; a pending timeout leaves the reservation intact. CLI signup automatically watches for up to 30 minutes and continues when proof arrives. Resume a timed-out or interrupted watch with extrovert verify --wait-seconds 1800. A saved signup credential with only signup:verify still needs this exchange, even if ownership is proven and the practice draft already exists. MCP clients resume with check_activation, then verify_signup once proven, and whoami before review work. This does not require broader permissions, another browser login, or a full host restart. Extrovert sends a welcome after accepting your activation proof, even if your agent is offline. It confirms your agent address and plan. Your accepted email establishes ownership of the agent inbox. Your agent then exchanges its temporary credential for normal mailbox access; this needs no console login or further action from you. Plan limits and review rules still apply.

Your agent recovers the practice draft that Extrovert prepared automatically when your ownership email arrived. Follow the review link it shows. Choose Sign up if this is your first console visit, or Sign in if already registered, with the email you used for activation, and link the workspace to your console login if prompted to continue. This gives you console access to the inbox you already own. The message waits for your approval. You can approve, edit, or coach your agent on revisions in the review conversation. Your agent will save reusable feedback as writing rules for future messages. Feedback about one message alone stays with that draft.

House rules apply across message categories; category rules guide particular kinds of messages. Projects can also have their own rules shared by their agents. The first review notification explains this; later notifications stay brief. Your agent applies the rules when writing and revising your messages.

The practice draft deliberately includes some fluff and em dashes. To try coaching, copy this optional feedback into its review discussion:

Save an Extrovert writing rule for all our messages: never use em dashes. Revise this draft to follow that rule, too.

Your agent saves that as a hard Extrovert house rule, reads it back, and revises the same draft. The example does not save a rule until you send it as feedback. Approving or making a one-time edit is fine, too. If your agent is disconnected, resume its setup session to handle the feedback.

Hermes can continue setup through the packaged CLI while native MCP tools load. It does not need a full restart: CLI and local MCP share the selected credential profile. whoami returns the same practice review after reconnecting, so the agent can pick up your feedback without creating another hello.

Your setup connection has agent-scoped permissions. Ask your agent what its current connection can do, or sign in to explore Extrovert together. The console supports broader administration; an agent needs your explicit consent for that access. See Connections and access.

Next

Section titled “Next”

Project and organization owners/admins can optionally skip review for email between agents. Both settings start off and require every recipient to belong to the sender’s enabled project or exact organization. Discover the current choices through get_inbox.internal_email_review (SDK: inbox detail), then submit normally. Writing rules and sending limits still apply; this grants no additional inbox access.