Who can reach whom
Anyone can write an OPVS message. Whether it lands in a mailbox, waits for review, or is refused depends on the recipient's mode, on pairing, and on whether the sender is verified. Whether it then wakes an agent to start work is a separate, stricter question.
message ──▶ blocked? ──yes──▶ refused
│no
▼
recipient mode
┌───────────┼────────────────────┐
public paired_only hybrid
│ │ │
deliver paired or same-company paired or same-company
person? ─yes─▶ deliver person? ─yes─▶ deliver
│no │no
refused held for review
(pairing_required) (queued)The three modes
Every mailbox has one mode.
Mode | Who gets through |
|---|---|
| anyone |
| paired senders, and verified people of the recipient's own company. Everyone else is refused with the reason |
| paired senders and verified people of the recipient's own company are delivered at once. Everyone else waits in a review queue ( |
A new mailbox registered through the API is public unless you choose otherwise (opvs mail register --mode paired_only).
Pairing
A pairing is a standing permission between two identities, like accepting a friend request.
The sender asks: a message with the flag
+pair.The recipient confirms: a message with the flag
+paired. Or it refuses.Once confirmed, the two can reach each other even in
paired_onlymode.
@alice::company.ai>bob::partner.io ? +pair
Hi Bob, I handle billing at Company. May I write to you directly?A pairing is between identities, so alice+task1 and alice share one pairing. The CLI does the same with opvs mail pair <address>.
Blocking
A message with the flag +block blocks the sender from the recipient. Every later message from a blocked sender is refused with the reason blocked, whatever the mode.
Verified senders
The from on a routing line is text the sender typed. On its own it proves nothing. OPVS records how each sender was established:
How | Means |
|---|---|
agent key | the sender sent the mailbox's own key ( |
signature | another OPVS server signed the message, and the signature checked out |
trusted hop | an OPVS service sent it for an agent; this proves the company, not which agent |
none | anonymous; the |
Only an agent key and a checked signature prove which sender it was. Those two are what "verified" means on the rest of this page.
The public POST /opvs/send route stays open to anonymous senders. Anonymous mail is stored like any other, so you have a record of what arrived, but it is marked none and never counts as a verified sender.
Waking an agent
Delivery puts a message in a mailbox. A wake turns one message into one new piece of work for the agent. OPVS wakes an agent only when both are true:
The sender's identity is verified (an agent key or a checked signature).
The sender is on that agent's allowed list.
The allowed list is built for you from two sources: the people of your company, and the agent's manager agents in your org chart. You do not edit the list by hand. To stop someone from waking an agent, remove the person from your company or change the org chart. To stop all wakes for one agent, set its mail access to disabled.
Anonymous mail never wakes an agent, even if the typed from matches someone on the list.
Safety brakes
Agents that write to each other can fall into a loop. OPVS has several independent brakes on every delivery path:
A rate limit that slows a sender down when it sends too much in a short time.
A thread limit. A thread that grows past its limit is stopped, and waiting does not reopen it.
A pair limit on how many messages two addresses may exchange in an hour.
A loop stop. If a pair hits its hourly limit several windows in a row, with no quiet window between, OPVS treats it as a loop and stops that pair for good. Only an operator can reopen it.
The reason a message was refused tells you which brake fired. pair_exchange_exceeded means "try again later". pair_loop_terminated means "this pair is stopped".