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

# Genie mailbox (self)

> Owner-facing provisioning and management of your genie's email inbox

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

<Note>
  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.
</Note>

***

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

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

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>
      UUID of the genie whose mailbox to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  The mailbox record.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Mailbox UUID.</ResponseField>
    <ResponseField name="agent_id" type="string">UUID of the owning genie.</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 provisioning is still in progress.</ResponseField>
    <ResponseField name="grant_id" type="string | null">Connection grant identifier, or `null`.</ResponseField>

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

    <ResponseField name="last_error" type="string | null">Error message if provisioning failed, or `null`.</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>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const mailbox = await ApiService.invoke("agent-mailboxes-self", "get", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  console.log(mailbox.email_address); // e.g. "support-bot@mail.helpgenie.ai"
  console.log(mailbox.status);        // e.g. "provisioned"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes-self",
      "action": "get",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "mbx-uuid-001",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "email_address": "support-bot@mail.helpgenie.ai",
      "account_id": "acct-abc123",
      "grant_id": null,
      "status": "provisioned",
      "last_error": null,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  }
  ```
</CodeGroup>

***

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

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

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>
      UUID of the genie to provision a mailbox for.
    </ParamField>

    <ParamField body="desiredLocalpart" type="string">
      Requested prefix for the mailbox email address (the part before the `@`). Must be 2–40 characters, using only lowercase letters, digits, and hyphens. Cannot start or end with a hyphen. Omit to let the system choose an address automatically.

      When provided for a genie that already has a mailbox, the current mailbox is deprovisioned and a new one is created at the requested address.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  The provisioned mailbox record.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Mailbox UUID.</ResponseField>
    <ResponseField name="agent_id" type="string">UUID of the owning genie.</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 provisioning is still in progress.</ResponseField>
    <ResponseField name="grant_id" type="string | null">Connection grant identifier, or `null`.</ResponseField>

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

    <ResponseField name="last_error" type="string | null">Error message if provisioning failed, or `null`.</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>

<Warning>
  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.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  // Provision with a custom address prefix
  const mailbox = await ApiService.invoke("agent-mailboxes-self", "provision", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    desiredLocalpart: "support-bot",
  });

  // Provision with a system-chosen address
  const mailbox = await ApiService.invoke("agent-mailboxes-self", "provision", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes-self",
      "action": "provision",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "desiredLocalpart": "support-bot"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "mbx-uuid-001",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "email_address": "support-bot@mail.helpgenie.ai",
      "account_id": "acct-abc123",
      "grant_id": null,
      "status": "provisioned",
      "last_error": null,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  }
  ```
</CodeGroup>

***

## Update mailbox

Suspends or resumes a genie's mailbox and/or updates its escalation address. At least one of `action` or `escalation_address` must be provided.

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

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>
      UUID of the genie whose mailbox to update.
    </ParamField>

    <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 messages the genie cannot handle. 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 the mailbox
  await ApiService.invoke("agent-mailboxes-self", "update", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    action: "suspend",
  });

  // Set an escalation address
  await ApiService.invoke("agent-mailboxes-self", "update", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    escalation_address: "oncall@example.com",
  });

  // Resume and clear escalation at the same time
  await ApiService.invoke("agent-mailboxes-self", "update", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    action: "resume",
    escalation_address: null,
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes-self",
      "action": "update",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "action": "suspend"
      }
    }'
  ```

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

***

## Delete mailbox

Permanently deprovisions a genie's email inbox. After deletion, the genie will no longer receive email.

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

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>
      UUID of the genie whose mailbox to deprovision.
    </ParamField>
  </Expandable>
</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 permanently deprovisions the mailbox and removes all associated records. It is idempotent if the mailbox is already absent in the mail system. The genie itself is not affected.
</Warning>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  await ApiService.invoke("agent-mailboxes-self", "delete", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes-self",
      "action": "delete",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```

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

***

## Send test email

Sends a test email into a genie's mailbox to verify it is provisioned and receiving correctly.

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

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

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>
      UUID of the genie whose mailbox to test.
    </ParamField>
  </Expandable>
</ParamField>

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

<ResponseField name="data" type="object">
  Result from the mail system's test endpoint. Shape may vary; a successful response indicates the test email was accepted for delivery.
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const result = await ApiService.invoke("agent-mailboxes-self", "test", undefined, {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1 \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "resource": "agent-mailboxes-self",
      "action": "test",
      "data": {
        "agentId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```

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

***

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

<Note>
  This action requires admin privileges. Non-admin callers receive a `FORBIDDEN` error.
</Note>

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

<ParamField body="action" type="string" required>
  Must be `"check-tenant-key"`
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="status" type="string">
      Current credential status as reported by the mail service (e.g. `"active"`). Returns `"unknown"` if the service does not provide a status.
    </ResponseField>

    <ResponseField name="revokedAt" type="string | null">
      ISO 8601 timestamp of when the credentials were revoked, or `null` if still active.
    </ResponseField>

    <ResponseField name="tenantId" type="string">
      Your team's mail tenant identifier.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const result = await ApiService.invoke("agent-mailboxes-self", "check-tenant-key");
  console.log(result.status);    // e.g. "active"
  console.log(result.revokedAt); // null if still valid
  ```

  ```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-self",
      "action": "check-tenant-key"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "status": "active",
      "revokedAt": null,
      "tenantId": "tenant-abc123"
    }
  }
  ```
</CodeGroup>

***

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

<Note>
  This action requires admin privileges. Non-admin callers receive a `FORBIDDEN` error.
</Note>

<Warning>
  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.
</Warning>

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

<ParamField body="action" type="string" required>
  Must be `"reprovision-tenant-key"`
</ParamField>

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

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="tenantId" type="string">
      Your team's mail tenant identifier (unchanged after re-provisioning).
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const result = await ApiService.invoke("agent-mailboxes-self", "reprovision-tenant-key");
  console.log(result.tenantId);
  ```

  ```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-self",
      "action": "reprovision-tenant-key"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "tenantId": "tenant-abc123"
    }
  }
  ```
</CodeGroup>

***

## Error codes

| Code               | Status | Description                                                                                                                                                   |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`     | 401    | Caller does not own the specified genie                                                                                                                       |
| `FORBIDDEN`        | 403    | Admin-only action called by a non-admin                                                                                                                       |
| `NOT_FOUND`        | 404    | Genie, mailbox, or mail credentials not found                                                                                                                 |
| `VALIDATION_ERROR` | 400    | Missing `agentId`, invalid `desiredLocalpart`, no update fields provided, invalid `escalation_address`, or mailbox already exists when no rename is requested |
| `INVALID_ACTION`   | 400    | Unknown action                                                                                                                                                |
| `INTERNAL_ERROR`   | 500    | Mail system error or local sync failure                                                                                                                       |