> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent mailboxes

> Admin management of genie email inbox provisioning state

`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.

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

***

## List all mailboxes

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

<ParamField body="resource" type="string" required>
  Must be `"agent-mailboxes"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"all"`
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="mailboxes" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="string">Mailbox UUID.</ResponseField>
        <ResponseField name="agent_id" type="string">UUID of the genie this mailbox belongs to.</ResponseField>
        <ResponseField name="agent_name" type="string | null">Display name of the owning genie.</ResponseField>
        <ResponseField name="user_id" type="string | null">User ID of the genie owner.</ResponseField>
        <ResponseField name="user_email" type="string | null">Email address of the genie owner.</ResponseField>
        <ResponseField name="user_name" type="string | null">Full name of the genie owner.</ResponseField>
        <ResponseField name="email_address" type="string">The provisioned mailbox email address.</ResponseField>
        <ResponseField name="account_id" type="string | null">Internal account reference used by the mail system, or `null` if not yet provisioned.</ResponseField>
        <ResponseField name="grant_id" type="string | null">OAuth grant identifier for the mailbox connection, or `null`.</ResponseField>

        <ResponseField name="status" type="string">
          Current provisioning status. One of `"provisioned"`, `"suspended"`, or `"unavailable"`.
        </ResponseField>

        <ResponseField name="last_error" type="string | null">Most recent provisioning error message, or `null` if healthy.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">Total number of mailboxes returned.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("agent-mailboxes", "all");
  const { mailboxes, count } = response;
  ```

  ```bash cURL theme={null}
  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"}'
  ```

  ```json Response theme={null}
  {
    "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,
          "created_at": "2024-01-10T08:00:00.000Z",
          "updated_at": "2024-01-10T08:00:00.000Z"
        }
      ],
      "count": 1
    }
  }
  ```
</CodeGroup>

***

## Update mailbox

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

<ParamField body="resource" type="string" required>
  Must be `"agent-mailboxes"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"update"`
</ParamField>

<ParamField body="id" type="string" required>
  The mailbox UUID.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="action" type="string">
      Lifecycle transition. Must be `"suspend"` or `"resume"`. Omit to leave the current status unchanged.
    </ParamField>

    <ParamField body="escalation_address" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="ok" type="boolean">
      `true` when the update was applied successfully.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // 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",
  });
  ```

  ```bash cURL theme={null}
  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" }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": { "ok": true }
  }
  ```
</CodeGroup>

***

## Delete mailbox

Deprovisions a mailbox and marks it as `"unavailable"`. After deletion, the genie creation flow will not automatically re-provision the mailbox.

<ParamField body="resource" type="string" required>
  Must be `"agent-mailboxes"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"delete"`
</ParamField>

<ParamField body="id" type="string" required>
  The mailbox UUID.
</ParamField>

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="ok" type="boolean">
      `true` when the mailbox was successfully deprovisioned.
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  This action deprovisions the mailbox in the mail system and removes the local mailbox record. It does not delete the underlying genie. The action is idempotent if the mailbox is already absent in the mail system (a `404` from the mail system is treated as success). The next update to the genie will automatically re-provision a fresh mailbox.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  await ApiService.invoke("agent-mailboxes", "delete", "mbx-uuid-001");
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": { "ok": true }
  }
  ```
</CodeGroup>

***

## 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                             |