mail.messages.read (first-party): Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest verification code in a burner. Never a message body, and never another person's mail. The caller must act for the person (on\_behalf\_of), except a burner read with the one-time token its create call returned.
### POST `/api/v1/agent-inboxes` Make and retire the addresses OpenVibe.Mail hands out for a person: a mask (a per-site address that delivers into their OpenVibe mailbox and nowhere else) and an agent inbox (mail.addresses.write (first-party): Make and retire the addresses OpenVibe.Mail hands out for a person: a mask (a per-site address that delivers into their OpenVibe mailbox and nowhere else) and an agent inbox (<agent>.<user>@openvibe.email). Turning a mask off makes its address bounce. The caller must act for the person (on\_behalf\_of); it never sends mail.
### GET `/api/v1/agent-inboxes/{id}/answering` Read and set whether an agent answers the mail sent to its own address: GET /api/v1/agent-inboxes/:id/answering and PUT /api/v1/agent-inboxes/:id/answering, both mail.inbox-answering@1. - Capabilities: [mail.agent.answering](/docs/capabilities/mail.agent.answering) - Visibility: first-party - Parameters: - `id` (path, required) - `agent_id` (query, required) — The agent's name in the address. - `address` (query, required) — The agent's inbox address. - `owner` (query, required) — The Network subject of the person whose switch it is. - `enabled` (query, required) — True when the agent answers the mail sent to this address. Off unless the person turned it on. - `changed_at` (query, required) — When the person last turned it on or off; null when they never have (it has been off since the address was made). - Input: [mail.inbox-answering@1](/docs/contracts/mail.inbox-answering) - Response: `application/json` [mail.inbox-answering@1](/docs/contracts/mail.inbox-answering) - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.agent.answering (first-party): Read and set whether an agent answers the mail sent to its own address: GET /api/v1/agent-inboxes/:id/answering and PUT /api/v1/agent-inboxes/:id/answering, both mail.inbox-answering@1. It is OFF by default and per agent; turning it on is what makes Mail publish mail.agent\_inbox.received for that address at all. The caller must act for the person (on\_behalf\_of), and another person's inbox is the same 404 as one that does not exist. Mail still publishes nothing for a sender on the person's block list or for a message the mail server marked as spam.
### PUT `/api/v1/agent-inboxes/{id}/answering` Read and set whether an agent answers the mail sent to its own address: GET /api/v1/agent-inboxes/:id/answering and PUT /api/v1/agent-inboxes/:id/answering, both mail.inbox-answering@1. - Capabilities: [mail.agent.answering](/docs/capabilities/mail.agent.answering) - Visibility: first-party - Parameters: - `id` (path, required) - Request body: `application/json` [mail.inbox-answering@1](/docs/contracts/mail.inbox-answering) - Response: `application/json` [mail.inbox-answering@1](/docs/contracts/mail.inbox-answering) - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.agent.answering (first-party): Read and set whether an agent answers the mail sent to its own address: GET /api/v1/agent-inboxes/:id/answering and PUT /api/v1/agent-inboxes/:id/answering, both mail.inbox-answering@1. It is OFF by default and per agent; turning it on is what makes Mail publish mail.agent\_inbox.received for that address at all. The caller must act for the person (on\_behalf\_of), and another person's inbox is the same 404 as one that does not exist. Mail still publishes nothing for a sender on the person's block list or for a message the mail server marked as spam.
### GET `/api/v1/agent-inboxes/{id}/messages` Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest - Capabilities: [mail.messages.read](/docs/capabilities/mail.messages.read) - Visibility: first-party - Parameters: - `id` (path, required) - Response: — - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.messages.read (first-party): Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest verification code in a burner. Never a message body, and never another person's mail. The caller must act for the person (on\_behalf\_of), except a burner read with the one-time token its create call returned.
### GET `/api/v1/burners` Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest - Capabilities: [mail.messages.read](/docs/capabilities/mail.messages.read) - Visibility: first-party - Response: — - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.messages.read (first-party): Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest verification code in a burner. Never a message body, and never another person's mail. The caller must act for the person (on\_behalf\_of), except a burner read with the one-time token its create call returned.
### GET `/api/v1/burners/{id}/code` Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest - Capabilities: [mail.messages.read](/docs/capabilities/mail.messages.read) - Visibility: first-party - Parameters: - `id` (path, required) - Response: — - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.messages.read (first-party): Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest verification code in a burner. Never a message body, and never another person's mail. The caller must act for the person (on\_behalf\_of), except a burner read with the one-time token its create call returned.
### GET `/api/v1/burners/{id}/messages` Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest - Capabilities: [mail.messages.read](/docs/capabilities/mail.messages.read) - Visibility: first-party - Parameters: - `id` (path, required) - Response: — - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.messages.read (first-party): Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest verification code in a burner. Never a message body, and never another person's mail. The caller must act for the person (on\_behalf\_of), except a burner read with the one-time token its create call returned.
### GET `/api/v1/masks` Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest - Capabilities: [mail.messages.read](/docs/capabilities/mail.messages.read) - Visibility: first-party - Response: — - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.messages.read (first-party): Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest verification code in a burner. Never a message body, and never another person's mail. The caller must act for the person (on\_behalf\_of), except a burner read with the one-time token its create call returned.
### POST `/api/v1/masks` Make and retire the addresses OpenVibe.Mail hands out for a person: a mask (a per-site address that delivers into their OpenVibe mailbox and nowhere else) and an agent inbox (mail.addresses.write (first-party): Make and retire the addresses OpenVibe.Mail hands out for a person: a mask (a per-site address that delivers into their OpenVibe mailbox and nowhere else) and an agent inbox (<agent>.<user>@openvibe.email). Turning a mask off makes its address bounce. The caller must act for the person (on\_behalf\_of); it never sends mail.
### GET `/api/v1/masks/{id}` Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest - Capabilities: [mail.messages.read](/docs/capabilities/mail.messages.read) - Visibility: first-party - Parameters: - `id` (path, required) - Response: — - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.messages.read (first-party): Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest verification code in a burner. Never a message body, and never another person's mail. The caller must act for the person (on\_behalf\_of), except a burner read with the one-time token its create call returned.
### DELETE `/api/v1/masks/{id}` Make and retire the addresses OpenVibe.Mail hands out for a person: a mask (a per-site address that delivers into their OpenVibe mailbox and nowhere else) and an agent inbox (mail.addresses.write (first-party): Make and retire the addresses OpenVibe.Mail hands out for a person: a mask (a per-site address that delivers into their OpenVibe mailbox and nowhere else) and an agent inbox (<agent>.<user>@openvibe.email). Turning a mask off makes its address bounce. The caller must act for the person (on\_behalf\_of); it never sends mail.
### POST `/api/v1/masks/{id}/disable` Make and retire the addresses OpenVibe.Mail hands out for a person: a mask (a per-site address that delivers into their OpenVibe mailbox and nowhere else) and an agent inbox (mail.addresses.write (first-party): Make and retire the addresses OpenVibe.Mail hands out for a person: a mask (a per-site address that delivers into their OpenVibe mailbox and nowhere else) and an agent inbox (<agent>.<user>@openvibe.email). Turning a mask off makes its address bounce. The caller must act for the person (on\_behalf\_of); it never sends mail.
### GET `/api/v1/me/mail` Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest - Capabilities: [mail.messages.read](/docs/capabilities/mail.messages.read) - Visibility: first-party - Response: — - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.messages.read (first-party): Read what arrived for a person's addresses: the addresses they own with their state and counts, and the metadata of a mask's, burner's or agent inbox's messages (sender, subject, time) plus the newest verification code in a burner. Never a message body, and never another person's mail. The caller must act for the person (on\_behalf\_of), except a burner read with the one-time token its create call returned.
### GET `/internal/mail/agents/{agent_id}/messages/{message_id}` Read one message sent to an agent's own address, in full plain text, as that agent acting for the person whose mailbox received it. - Capabilities: [mail.agent.read](/docs/capabilities/mail.agent.read) - Visibility: first-party - Parameters: - `agent_id` (path, required) - `message_id` (path, required) - Response: `application/json` [mail.agent-inbox-message@1](/docs/contracts/mail.agent-inbox-message) - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.agent.read (first-party): Read one message sent to an agent's own address, in full plain text, as that agent acting for the person whose mailbox received it. GET /internal/mail/agents/:agent\_id/messages/:message\_id answers mail.agent-inbox-message@1: the sender, the addresses the mail server stamped at delivery, the subject, the text cut to 4000 characters, and the two threading headers a reply needs. Never the HTML and never an attachment. The token must name the person (on\_behalf\_of), the agent must be one of that person's inboxes, and the message must have been delivered to that address; anything else is the same 404 as a message that does not exist. Loopback only; granted to OpenVibe.Actor alone, which reads a letter and answers it under the person's approval policy.
### POST `/internal/mail/agents/{agent_id}/reply` Send a reply FROM an agent's own address, as that agent acting for the person whose mailbox receives its mail. - Capabilities: [mail.agent.reply](/docs/capabilities/mail.agent.reply) - Visibility: first-party - Parameters: - `agent_id` (path, required) - Request body: `application/json` [mail.agent-reply-request@1](/docs/contracts/mail.agent-reply-request) - Response: `application/json` [mail.agent-reply-result@1](/docs/contracts/mail.agent-reply-result) - Errors: [errors.problem@1](/docs/contracts/errors.problem) (application/problem+json) Descriptionmail.agent.reply (first-party): Send a reply FROM an agent's own address, as that agent acting for the person whose mailbox receives its mail. POST /internal/mail/agents/:agent\_id/reply takes mail.agent-reply-request@1 and answers mail.agent-reply-result@1. The reply is plain text, comes from <agent>.<user>@openvibe.email and from nothing else, and carries In-Reply-To and References so it stays in the thread; the recipient is the sender of the message being answered, or the same address named in to, and never a stranger the message did not come from. The recipient is therefore never new: this is an answer, not a first letter. The token must name the person (on\_behalf\_of) and the agent must be one of their inboxes. Loopback only; granted to OpenVibe.Actor alone, which sends the reply the person approved.