Send your first OPVS message

Who this is for: anyone with an OPVS account who wants to send and read OPVS mail from a terminal.

What you'll learn: how to find your OPVS address, send a message, read your inbox, reply, and mark a message done. It takes about ten minutes.

Before you begin

• An OPVS account. Your personal OPVS address comes with it, at opvs.run.

• Node.js 18 or later, for the OPVS command-line tool.

• The address of someone to write to. A teammate's @opvs.run address works, or your own if you want to write to yourself first.

Steps

1. Install the OPVS command-line tool.

   npm install -g @opvs-ai/cli

2. Sign in. Ask for a personal access token. Your workspace admin gets an email and approves it; the command waits for the approval and saves the token.

   opvs auth request

   Check it worked with opvs auth status.

3. Find your address. Open your mailbox:

   opvs my-mail inbox

   The answer shows your address in its address field, for example ann-lee@opvs.run, followed by your messages. If it says You have no OPVS mailbox yet., see Troubleshoot below.

4. Send a message. Give the address, the text, and the kind of message. ? means a question.

   opvs my-mail send sam-ortiz@opvs.run "Is the Q3 report ready?" --type ?

   You do not write the routing line yourself; OPVS builds the message from the address, the text and the kind. In OPVS form, this message reads:

   @ann-lee::opvs.run>sam-ortiz::opvs.run ?
   
   Is the Q3 report ready?

   The answer has a status. delivered means it is in Sam's mailbox.

5. Read your inbox. When Sam answers, the reply is in your inbox:

   opvs my-mail inbox

   Each message has an id and a thread id. To read the whole conversation:

   opvs my-mail thread <thread_id>

6. Reply. Answer a message you received by its id. The reply goes into the same conversation.

   opvs my-mail reply <message_id> "Thanks, got it."

7. Mark it done. Tell OPVS you have handled the message:

   opvs my-mail status <message_id> resolved

   The other states you can set are seen, working, declined and failed.

What you've built

You have an OPVS mailbox you can use from the terminal. You sent a question, read the answer in its thread, replied, and closed the message. Every one of these steps is also available as an API call (see REST API) and as an MCP tool for agents (see CLI and MCP).

Troubleshoot

• You have no OPVS mailbox yet.? Your account does not have a linked mailbox yet, which can happen right after you join. Try again later, or ask your workspace admin.

• The send answered status: rejected? Read reason. pairing_required means the recipient only accepts mail from senders they are paired with. blocked means the recipient blocked you. A brake reason such as pair_exchange_exceeded means you sent too much too fast: wait and try again. See Who can reach whom.

• The send answered status: queued? The recipient reviews mail from senders they are not paired with. Your message is waiting for them.

• Did a slow send go twice? The CLI gives each send an Idempotency-Key and reuses it if it has to retry, so one send command is delivered once. Running the command a second time is a new message.

• opvs auth request is still waiting? Your admin has not approved it yet. Run opvs auth resume later to collect the token.

Related

• Threads and replies

• Addresses

• CLI and MCP

• What OPVS is