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", "suspended", or "unavailable".

string | null

Error message if provisioning failed, or null.

boolean

Whether the mailbox is currently in test mode.

string | null

Fallback email address for messages the genie cannot handle, or null if not set.

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"
console.log(mailbox.escalation_address); // e.g. "oncall@example.com" or 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"
    }
  }'

{
  "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,
    "test_mode": false,
    "escalation_address": "oncall@example.com",
    "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.

boolean

Whether the mailbox is currently in test mode.

string | null

Fallback email address for messages the genie cannot handle, or null if not set.

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,
    "test_mode": false,
    "escalation_address": 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, updates its escalation address, and/or toggles test mode. At least one of action, escalation_address, or test_mode 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

Enable or disable test mode for the mailbox. When true, the mailbox processes emails in a sandboxed mode. Stored locally and synced to the mail service to keep both sides in agreement.

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

// Enable test mode
await ApiService.invoke("agent-mailboxes-self", "update", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  test_mode: true,
});

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 removes a genie’s email inbox — deletes the local record and fully removes the account from the mail system. After deletion, the genie will no longer receive email until a new mailbox is provisioned.

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

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.

string

required

Must be "agent-mailboxes-self"

string

required

Must be "conversations"

object

required

Show properties

string

required

UUID of the genie whose mailbox threads to list.

string

Filter by conversation state. One of "open", "escalated", or "closed".

string

Filter by the genie’s last decision on a thread (e.g. "replied", "escalated", "ignored").

string

Full-text search across conversation subjects and body snippets.

string

ISO 8601 timestamp — only threads updated after this time.

string

Pagination cursor returned from a previous page.

number

Maximum number of threads to return.

string

Sort order. One of "date_asc", "date_desc", "sender_asc", or "sender_desc".

boolean

object

Conversation threads and pagination cursor. Shape is determined by the mail system response.

const response = await ApiService.invoke("agent-mailboxes-self", "conversations", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  state: "open",
  limit: 20,
});

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": "conversations",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "state": "open",
      "limit": 20
    }
  }'

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

Show properties

string

required

UUID of the genie the thread belongs to.

string

required

Mail system conversation ID (returned in the conversations action result).

boolean

object

Full conversation thread with messages and decision history.

const response = await ApiService.invoke("agent-mailboxes-self", "conversation-detail", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  conversationId: "mail-conv-abc123",
});

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": "conversation-detail",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "conversationId": "mail-conv-abc123"
    }
  }'

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

Show properties

string

required

UUID of the genie whose mailbox the reply is sent from.

string

required

Mail system conversation ID (returned in the conversations action result).

string

required

Plain-text body of the reply. Must be non-empty.

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.

const result = await ApiService.invoke("agent-mailboxes-self", "reply", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  conversationId: "mail-conv-abc123",
  body_text: "Thanks for reaching out — I'll look into this and follow up shortly.",
});

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": "reply",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "conversationId": "mail-conv-abc123",
      "body_text": "Thanks for reaching out — I'\''ll look into this and follow up shortly."
    }
  }'

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

Show properties

string

required

UUID of the genie whose local mailbox row to update.

string

Updated mailbox status from the mail system. One of "pending", "provisioned", "suspended", "failed", or "unavailable".

string

Updated provisioned email address, or null to clear.

string

Error text to record, or null to clear.

boolean

await ApiService.invoke("agent-mailboxes-self", "sync", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  status: "provisioned",
  email_address: "support-bot@mail.helpgenie.ai",
  last_error: 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": "sync",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "provisioned",
      "email_address": "support-bot@mail.helpgenie.ai",
      "last_error": null
    }
  }'

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`, `conversationId`, or `body_text`; invalid `desiredLocalpart`; no update fields provided; invalid `escalation_address`; invalid `test_mode` type; 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

List email conversations

Get email conversation detail

Reply to a conversation

Sync mailbox status

Check mail credentials (admin only)

Re-provision mail credentials (admin only)

Error codes

​Get mailbox

​Provision mailbox

​Update mailbox

​Delete mailbox

​Send test email

​List email conversations

​Get email conversation detail

​Reply to a conversation

​Sync mailbox status

​Check mail credentials (admin only)

​Re-provision mail credentials (admin only)

​Error codes

Get mailbox

Provision mailbox

Update mailbox

Delete mailbox

Send test email

List email conversations

Get email conversation detail

Reply to a conversation

Sync mailbox status

Check mail credentials (admin only)

Re-provision mail credentials (admin only)

Error codes