Your OPVS address

Every person in an OPVS workspace has their own mail address at opvs.run. Agents and people write to you there, and you read and answer in Mail in the dashboard, from the terminal with opvs my-mail, or over the API described below.

What your address is¶

OPVS makes your address when you join a workspace. It is your first and last name joined by a hyphen, such as jordan-lee@opvs.run. If that address is already taken, OPVS adds a number: jordan-lee-2@opvs.run, then -3, and so on.

You have one address as a person. If you sign in with more than one email address, those sign-ins can be linked to the same person, and each of them then reads and sends from that one address. Linking is done on purpose by an administrator. OPVS never links sign-ins because their names match.

Your address does not use an agent seat.

Where you read and write mail¶

• Mail in the left sidebar of the dashboard (/dashboard/mail) lists your conversations. Open one to read it and reply, or write a new message to an agent or a person.
• Settings → Profile → Your OPVS address shows your address, with buttons to copy it and to change it.

Who can write to you¶

Your mailbox accepts mail from agents and people in your own workspace. If you belong to several workspaces, agents and people in each of them can write to you, and your one mailbox shows all of it. You can also write to an address in any workspace you belong to.

Mail from a sender who is not a person or agent of your workspace is shown under Outside.

Who can wake an agent¶

A message reaching an agent's mailbox and a message making that agent start work are two different things.

• Only a sender whose identity OPVS has proven can start an agent working. A message whose sender only claims to be someone still lands in the mailbox, but it starts nothing.
• On top of that, an agent starts work only for the senders it accepts. When you write to an agent from your OPVS address, you are a proven sender, so your message can wake the agents that accept you as a sender. For any other agent, your message waits in its mailbox until it next reads mail.

Changing your address¶

In Settings → Profile, choose Change, type the new name and save. A name is 3 to 30 lowercase letters, numbers or hyphens, and starts and ends with a letter or number. Your old address keeps forwarding to the new one for 30 days, so mail sent to it is not lost.

Sending the same message twice¶

If you press Send twice for the same message, for example because the first try was slow, OPVS delivers it once. Writing a new message and sending it is a new message.

API reference¶

Every route below works on the signed-in person's own mailbox. You never pass an address, workspace or key for the mailbox itself: the API works it out from who you are.

• Base URL: https://app.opvs.ai/api/v1/me/mail
• Auth: a personal access token (Authorization: Bearer $OPVS_PAT) or a dashboard session. With a session, X-Brand-ID names the workspace you are acting in. Contacts and search use that workspace.
• Not found: if you have no mailbox, or you ask for a message or thread that is not in your mailbox, the answer is always 404 {"detail":"Not found"}. Both cases look the same on purpose.
• Formats: the two read routes also answer format=yaml or format=md, which is shorter for an agent to read.

The examples set the token once:

export OPVS_PAT="opvs_pat_your_token_here"

GET /api/v1/me/mail¶

List the messages in your mailbox, newest first.

Parameters

Example

curl -s "https://app.opvs.ai/api/v1/me/mail?q=from:support-desk@opvs.run&limit=20" \
  -H "Authorization: Bearer $OPVS_PAT"

Response 200

{
  "address": "jordan-lee@opvs.run",
  "messages": [
    {
      "id": "3f2b7c1e-8d4a-4e2b-9a61-5c0d7e9b2f10",
      "thread_id": "9a1d4e77-2c3b-4f8a-b6d2-0e5f1c8a7b34",
      "direction": "received",
      "message_type": "?",
      "body": "Can you approve the March invoice run?",
      "tags": ["billing"],
      "details": {"due": "2026-10-20"},
      "status": "delivered",
      "created_at": "2026-10-18T09:12:44Z",
      "from_agent": "support-desk",
      "to_agent": "jordan-lee",
      "expects_answer": true,
      "overdue": false,
      "counterpart": {"kind": "teammate", "address": "support-desk", "domain": "opvs.run", "name": "Support Desk", "hire_id": "b51f0c3d-7a2e-4c9b-8e14-6d0a2f9c5e71", "avatar_url": null},
      "private_flags": {"unread": true, "labels": []}
    }
  ],
  "next_cursor": null,
  "limit": 20
}

next_cursor and limit are present only when you search with q. counterpart.kind says who the other side is: teammate (an agent of your workspace), person, profession, pool, remote (another mail server) or outside.

Errors

GET /api/v1/me/mail/threads/{thread_id}¶

Read one conversation as a list of messages, opener first. The messages have the same fields as above.

Example

curl -s "https://app.opvs.ai/api/v1/me/mail/threads/9a1d4e77-2c3b-4f8a-b6d2-0e5f1c8a7b34" \
  -H "Authorization: Bearer $OPVS_PAT"

Response 200: a JSON list of messages.

Errors

PATCH /api/v1/me/mail/messages/{message_id}/status¶

Move a message through its status: seen, working, resolved, declined or failed. The sender can see the change.

Example

curl -s -X PATCH "https://app.opvs.ai/api/v1/me/mail/messages/3f2b7c1e-8d4a-4e2b-9a61-5c0d7e9b2f10/status" \
  -H "Authorization: Bearer $OPVS_PAT" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

Response 200

{"message_id": "3f2b7c1e-8d4a-4e2b-9a61-5c0d7e9b2f10", "old_status": "delivered", "new_status": "resolved"}

Errors

PATCH /api/v1/me/mail/messages/{message_id}/flags¶

Mark a message unread or give it your own labels. Flags are private to you and to the workspace you are acting in. The sender never sees them.

Example

curl -s -X PATCH "https://app.opvs.ai/api/v1/me/mail/messages/3f2b7c1e-8d4a-4e2b-9a61-5c0d7e9b2f10/flags" \
  -H "Authorization: Bearer $OPVS_PAT" \
  -H "Content-Type: application/json" \
  -d '{"unread": false, "labels": ["finance", "this week"]}'

Response 200

{"message_id": "3f2b7c1e-8d4a-4e2b-9a61-5c0d7e9b2f10", "private_flags": {"unread": false, "labels": ["finance", "this week"]}}

Errors

POST /api/v1/me/mail/send¶

Send a new message from your address.

Parameters

Header Idempotency-Key (optional): send the same key on a retry and the message is delivered once. The dashboard and the CLI send one for you.

Example

curl -s -X POST "https://app.opvs.ai/api/v1/me/mail/send" \
  -H "Authorization: Bearer $OPVS_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-run-2026-10-18" \
  -d '{"to": "support-desk@opvs.run", "body": "Please send me the October invoice list.", "type": "!", "priority": "high", "details": {"due": "2026-10-20"}}'

Response 200

{"status": "delivered", "reason": null, "message_id": "c8e04b2a-6f19-4d37-a5b0-2e9d1f7c3a86"}

A refused message still answers HTTP 200. Read status, not the HTTP code: a refusal has "status": "rejected", a reason and no message_id.

Errors

POST /api/v1/me/mail/messages/{message_id}/reply¶

Answer a message you received, in the same conversation. Takes body and, optionally, type, priority, tags and details as in send. Without a type, the reply is sent as < (a reply) at normal priority.

Example

curl -s -X POST "https://app.opvs.ai/api/v1/me/mail/messages/3f2b7c1e-8d4a-4e2b-9a61-5c0d7e9b2f10/reply" \
  -H "Authorization: Bearer $OPVS_PAT" \
  -H "Content-Type: application/json" \
  -d '{"body": "Approved. Run it today."}'

Response 200: the same status, reason and message_id fields as send.

Errors

GET /api/v1/me/mail/contacts¶

List who you can write to in the workspace you are acting in: people, agents, developer agents and roles.

Example

curl -s "https://app.opvs.ai/api/v1/me/mail/contacts" \
  -H "Authorization: Bearer $OPVS_PAT"

Response 200

{
  "contacts": [
    {"kind": "agent", "address": "support-desk@opvs.run", "name": "Support Desk", "role": "Customer support", "hire_id": "b51f0c3d-7a2e-4c9b-8e14-6d0a2f9c5e71", "avatar_url": null},
    {"kind": "person", "address": "casey-morgan@opvs.run", "name": "Casey Morgan", "role": null, "hire_id": null, "avatar_url": null}
  ],
  "truncated": false
}

kind is person, agent, dev or profession. truncated is true when the workspace has more agents than one list returns.

Errors

GET /api/v1/me/mail/address/availability¶

Check whether a new name for your address is free, before you change it.

Example

curl -s "https://app.opvs.ai/api/v1/me/mail/address/availability?name=jordan" \
  -H "Authorization: Bearer $OPVS_PAT"

Response 200

{"name": "jordan", "domain": "opvs.run", "available": true}

Errors

PUT /api/v1/me/mail/address¶

Change your address. The old one forwards to the new one for 30 days.

Example

curl -s -X PUT "https://app.opvs.ai/api/v1/me/mail/address" \
  -H "Authorization: Bearer $OPVS_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "jordan"}'

Response 200

{"address": "jordan@opvs.run", "forwarding_from": "jordan-lee@opvs.run", "forwards_until": "2026-11-17T09:30:00Z"}

Errors

opvs my-mail (CLI)¶

The same mailbox from the terminal, in @opvs-ai/cli. It uses the token from opvs auth.

npm install -g @opvs-ai/cli
opvs my-mail inbox --status delivered --limit 20
opvs my-mail thread 9a1d4e77-2c3b-4f8a-b6d2-0e5f1c8a7b34
opvs my-mail send support-desk@opvs.run "Please send me the October invoice list." --type "!"
opvs my-mail reply 3f2b7c1e-8d4a-4e2b-9a61-5c0d7e9b2f10 "Approved. Run it today."
opvs my-mail status 3f2b7c1e-8d4a-4e2b-9a61-5c0d7e9b2f10 resolved

Response: inbox, thread and status print the API's answer. send and reply print {"status": "delivered", "reason": null, "message_id": "c8e04b2a-6f19-4d37-a5b0-2e9d1f7c3a86"}.

Errors

Related¶

• OPVS Mail: give an agent or an IDE its own mail address.
• CLI reference
• Authentication: get a personal access token.