Skip to main content
agent-mailboxes-self is the owner-facing surface for managing the email inbox attached to your own genie. Every action is scoped to the caller’s genie — you can only manage mailboxes you own.
To read the current mailbox state you can use either this resource’s get action (documented below) or the genies resource (get or all action), which includes a mailbox field in every full genie response.

Get mailbox

Returns the current mailbox record for a genie you own. Use this to check provisioning status, retrieve the mailbox email address, or detect errors after provisioning.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "get"
object
required
boolean
Whether the request succeeded.
object
The mailbox record.

Provision mailbox

Creates an email inbox for a genie that doesn’t have one yet. If a desiredLocalpart is provided and the genie already has a mailbox, the existing inbox is deprovisioned and a new one is created at the requested address. A Listener genie’s mailbox is created listen-only (mode: "listen"): a forwarding address for the business’s own support inbox that never replies on its own. A listen- prefix (for example listen-acme) is a good choice for desiredLocalpart. Renaming a listen-only mailbox keeps it listen-only. New genies don’t get a mailbox automatically — call this action (or pass provisionMailbox: true when creating or cloning a genie) to set one up. If the genie has no mailbox record here but the mail system still holds a live mailbox for it, that mailbox is restored under its current address instead of creating a new one. desiredLocalpart is ignored in that case — rename the mailbox afterwards with a second provision call.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "provision"
object
required
boolean
Whether the request succeeded.
object
The provisioned mailbox record.
When desiredLocalpart is provided for a genie that already has a mailbox, the existing inbox is permanently deprovisioned before the new one is created. Any emails in the old inbox will be lost. If the mail system refuses to remove the old inbox, the request fails and the existing mailbox is left unchanged.
Returns an INTERNAL_ERROR with the mailbox’s last_error when provisioning ends in status "failed", or when no mailbox record exists after the request.

Update mailbox

Suspends or resumes a genie’s mailbox, updates its escalation address, and/or toggles test mode, attaching resources to replies, approve-before-send or the customer holding note on escalation. At least one of action, escalation_address, test_mode, attach_resources, operating_mode, or skip_forward_ack must be provided. This action never creates a mailbox. If the genie has no mailbox record here but the mail system still holds one, it is restored first; otherwise the request returns NOT_FOUND.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "update"
object
required
boolean
object

Delete mailbox

Permanently removes a genie’s email inbox — deletes the local record and fully removes the account from the mail system. After deletion, the genie stays without a mailbox — and receives no email — until a new one is created with provision. If no local record exists, an orphaned mailbox for the genie is still looked up in the mail system and deleted.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "delete"
object
required
boolean
object
This action fully removes the mailbox from the mail system and deletes all associated records. The action is idempotent — a 404 from the mail system is treated as success. If the mail system refuses the delete, the request fails and the mailbox record is restored unchanged. The genie itself is not affected.

Send test email

Sends a test email into a genie’s mailbox to verify it is provisioned and receiving correctly. A missing mailbox record is restored from the mail system first when the mail system still holds the mailbox (a mailbox is never created here); fails if the mailbox has no mail account yet or has been deprovisioned.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "test"
object
required
boolean
object
Result from the mail system’s test endpoint. Shape may vary; a successful response indicates the test email was accepted for delivery.

List email conversations

Lists email conversation threads for a genie’s mailbox, fetched from the mail system. Returns the genie owner’s threads — callers must own the specified genie. A missing mailbox record is restored from the mail system first when the mail system still holds the mailbox (a mailbox is never created here); fails if the mailbox has no mail account yet.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "conversations"
object
required
boolean
object
Conversation threads and pagination cursor. Shape is determined by the mail system response.

Get email conversation detail

Returns the full message and decision history for a single email conversation thread from the mail system.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "conversation-detail"
object
required
boolean
object
Full conversation thread with messages and decision history.

Reply to a conversation

Sends a human-written reply on an email conversation thread via the genie’s mailbox. The genie’s automated handling is paused for that thread after a reply is sent, so the human can take over without the genie also responding.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "reply"
object
required
boolean
object
Result from the mail system’s reply endpoint. Shape may vary; a successful response indicates the reply was accepted for delivery.
Sending a reply automatically pauses the genie’s handling of that thread. The genie will not respond further unless the thread is manually resumed.

Approve or dismiss a waiting reply

When the mailbox’s operating_mode is "draft_only", each reply the genie writes waits for approval. List waiting conversations with conversations and decisionStatus: "proposed", then read the conversation with conversation-detail: the waiting reply is the decision with action: "send" and status: "proposed", and its draft_subject/draft_body are what will be sent. Approving or editing sends a real email to the customer from the genie’s mailbox address.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "decide"
object
required
boolean
object
Returns CONFLICT when the reply was already sent or dismissed, or when the customer wrote again and a newer reply replaced it.

Sync mailbox status

Inbound callback from the mail system to mirror a status, address, or error change into the local mailbox record. Writes locally only — it never calls back out to the mail system. At least one of status, email_address, or last_error must be provided.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "sync"
object
required
boolean

Check mail credentials (admin only)

Verifies that your team’s stored mail service credentials are still valid and active. Use this to diagnose email delivery failures — for example, when the mail service returns authentication errors and you need to confirm whether the credentials have been rotated or revoked.
This action requires admin privileges. Non-admin callers receive a FORBIDDEN error.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "check-tenant-key"
boolean
Whether the request succeeded.
object

Re-provision mail credentials (admin only)

Reissues your team’s mail service credentials, replacing the current key with a fresh one. Use this when check-tenant-key reports that credentials are invalid or revoked.
This action requires admin privileges. Non-admin callers receive a FORBIDDEN error.
Re-provisioning invalidates the current credentials immediately. Any in-flight requests using the old key will fail until they re-authenticate. Only call this when check-tenant-key confirms the existing credentials are no longer valid.
string
required
Must be "agent-mailboxes-self"
string
required
Must be "reprovision-tenant-key"
boolean
Whether the request succeeded.
object

Error codes