Genie mailbox (self)

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

Show properties

string

required

UUID of the genie whose mailbox to retrieve.

boolean

Whether the request succeeded.

object

The mailbox record.

Show properties

string

Mailbox UUID.

string

UUID of the owning genie.

string

The provisioned mailbox email address.

string | null

Internal account reference used by the mail system, or null if provisioning is still in progress.

string | null

Connection grant identifier, or null.

string

Current provisioning status. One of "provisioned", "pending", "failed", or "suspended".

string | null

Error message if provisioning failed, or null.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

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"

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"
    }
  }'

{
  "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"
  }
}

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.

string

required

Must be "agent-mailboxes-self"

string

required

Must be "provision"

object

required

Show properties

string

required

UUID of the genie to provision a mailbox for.

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.

boolean

Whether the request succeeded.

object

The provisioned mailbox record.

Show properties

string

Mailbox UUID.

string

UUID of the owning genie.

string

The provisioned mailbox email address.

string | null

Internal account reference used by the mail system, or null if provisioning is still in progress.

string | null

Connection grant identifier, or null.

string

Current provisioning status. One of "provisioned", "pending", "failed", or "suspended".

string | null

Error message if provisioning failed, or null.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

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.

// 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",
});

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"
    }
  }'

{
  "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"
  }
}

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.

string

required

Must be "agent-mailboxes-self"

string

required

Must be "update"

object

required

Show properties

string

required

UUID of the genie whose mailbox to update.

string

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

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.

boolean

object

Show properties

boolean

true when the update was applied successfully.

// 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,
});

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"
    }
  }'

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

Delete mailbox

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

string

required

Must be "agent-mailboxes-self"

string

required

Must be "delete"

object

required

Show properties

string

required

UUID of the genie whose mailbox to deprovision.

boolean

object

Show properties

boolean

true when the mailbox was successfully deprovisioned.

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.

await ApiService.invoke("agent-mailboxes-self", "delete", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
});

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"
    }
  }'

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

Send test email

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

string

required

Must be "agent-mailboxes-self"

string

required

Must be "test"

object

required

Show properties

string

required

UUID of the genie whose mailbox to test.

boolean

object

Result from the mail system’s test endpoint. Shape may vary; a successful response indicates the test email was accepted for delivery.

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

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"
    }
  }'

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

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

Show properties

string

Current credential status as reported by the mail service (e.g. "active"). Returns "unknown" if the service does not provide a status.

string | null

ISO 8601 timestamp of when the credentials were revoked, or null if still active.

string

Your team’s mail tenant identifier.

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

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"
  }'

{
  "success": true,
  "data": {
    "status": "active",
    "revokedAt": null,
    "tenantId": "tenant-abc123"
  }
}

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

Show properties

string

Your team’s mail tenant identifier (unchanged after re-provisioning).

const result = await ApiService.invoke("agent-mailboxes-self", "reprovision-tenant-key");
console.log(result.tenantId);

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"
  }'

{
  "success": true,
  "data": {
    "tenantId": "tenant-abc123"
  }
}

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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Genie mailbox (self)

Get mailbox

Provision mailbox

Update mailbox

Delete mailbox

Send test email

Check mail credentials (admin only)

Re-provision mail credentials (admin only)

Error codes

​Get mailbox

​Provision mailbox

​Update mailbox

​Delete mailbox

​Send test email

​Check mail credentials (admin only)

​Re-provision mail credentials (admin only)

​Error codes

Get mailbox

Provision mailbox

Update mailbox

Delete mailbox

Send test email

Check mail credentials (admin only)

Re-provision mail credentials (admin only)

Error codes