Agent mailboxes

agent-mailboxes is an admin-only resource for monitoring and managing the email inbox attached to each genie. Every genie that has email reception enabled gets a provisioned mailbox entry; this resource lets admins view the full mailbox roster and suspend, resume, or deprovision individual mailboxes.

All actions on this resource require an internal admin account. Requests from non-admin users are rejected with 403 Forbidden.

List all mailboxes

Returns every genie mailbox across all users, joined with the owning genie and user details.

string

required

Must be "agent-mailboxes"

string

required

Must be "all"

object

Show properties

number

Maximum number of mailboxes to return. Default 50, max 500.

number

Number of records to skip for pagination. Default 0.

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

string

Mailbox UUID.

string

UUID of the genie this mailbox belongs to.

string | null

Display name of the owning genie.

string | null

User ID of the genie owner.

string | null

Email address of the genie owner.

string | null

Full name of the genie owner.

string

The provisioned mailbox email address.

string | null

Internal account reference used by the mail system, or null if not yet provisioned.

string | null

OAuth grant identifier for the mailbox connection, or null.

string

Current provisioning status. One of "provisioned", "suspended", or "unavailable".

string | null

Most recent provisioning error message, or null if healthy.

boolean

Whether the mailbox is currently in test mode.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

number

Total number of mailboxes matching the query.

number

The page size used for this request.

number

The offset used for this request.

const response = await ApiService.invoke("agent-mailboxes", "all", undefined, { limit: 50, offset: 0 });
const { mailboxes, count, limit, offset } = response;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource": "agent-mailboxes", "action": "all", "data": {"limit": 50, "offset": 0}}'

{
  "success": true,
  "data": {
    "mailboxes": [
      {
        "id": "mbx-uuid-001",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "agent_name": "Support Genie",
        "user_id": "usr-uuid-456",
        "user_email": "owner@example.com",
        "user_name": "Jane Smith",
        "email_address": "support-genie@mail.helpgenie.ai",
        "account_id": "acct-abc123",
        "grant_id": "grant-xyz789",
        "status": "provisioned",
        "last_error": null,
        "test_mode": false,
        "created_at": "2024-01-10T08:00:00.000Z",
        "updated_at": "2024-01-10T08:00:00.000Z"
      }
    ],
    "count": 1,
    "limit": 50,
    "offset": 0
  }
}

Update mailbox

Suspends or resumes a mailbox and/or updates the escalation address. At least one field (action or escalation_address) must be provided.

string

required

Must be "agent-mailboxes"

string

required

Must be "update"

string

required

The mailbox UUID.

object

required

Show properties

string

Lifecycle transition. Must be "suspend" or "resume". Omit to leave the current status unchanged.

string | null

Fallback email address for unhandled messages. Must be a valid email address, or null to clear the current value. Omit this key entirely to leave it unchanged.

boolean

object

Show properties

boolean

true when the update was applied successfully.

// Suspend a mailbox
await ApiService.invoke("agent-mailboxes", "update", "mbx-uuid-001", {
  action: "suspend",
});

// Update escalation address only
await ApiService.invoke("agent-mailboxes", "update", "mbx-uuid-001", {
  escalation_address: "oncall@example.com",
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "agent-mailboxes",
    "action": "update",
    "id": "mbx-uuid-001",
    "data": { "action": "suspend" }
  }'

{
  "success": true,
  "data": { "ok": true }
}

Delete mailbox

Permanently removes a mailbox — deletes the local record and fully removes the account from the mail system. The next update to the genie will automatically re-provision a fresh mailbox.

string

required

Must be "agent-mailboxes"

string

required

Must be "delete"

string

required

The mailbox UUID.

boolean

object

Show properties

boolean

true when the mailbox was successfully deprovisioned.

This action fully removes the mailbox from the mail system and deletes the local record. It does not delete the underlying genie. The action is idempotent — a 404 from the mail system is treated as success. The next update to the genie will automatically re-provision a fresh mailbox.

await ApiService.invoke("agent-mailboxes", "delete", "mbx-uuid-001");

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "agent-mailboxes",
    "action": "delete",
    "id": "mbx-uuid-001"
  }'

{
  "success": true,
  "data": { "ok": true }
}

Error codes

Code	Status	Description
`FORBIDDEN`	403	Caller is not an internal admin
`NOT_FOUND`	404	Mailbox not found
`VALIDATION_ERROR`	400	Missing ID, no valid update fields, or invalid `escalation_address`
`INVALID_ACTION`	400	Unknown action
`INTERNAL_ERROR`	500	Mail system error or local sync failure

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List all mailboxes

Update mailbox

Delete mailbox

Error codes

​List all mailboxes

​Update mailbox

​Delete mailbox

​Error codes

List all mailboxes

Update mailbox

Delete mailbox

Error codes