Inbox Layout

The inbox layout displays list data as a sidebar of items with an expandable detail panel. When you select an item from the list, its full details appear alongside, similar to how email applications work.

This layout is ideal for workflows where you need to quickly scan through records and inspect individual items without losing context of the broader list.

When to use inbox layout

The inbox layout works well for:

• Support tickets - Scan ticket summaries while reviewing full ticket details
• Order processing - Work through orders one by one with full order information visible
• Message queues - Review incoming messages with the full message content displayed
• Task management - Triage tasks while seeing all task details

For tabular data where you need to see many fields at once, the grid (table) layout is more appropriate. For visual content, consider the gallery layout. For status-based workflows, the board (kanban) layout works well. See display layouts for all available options.

Basic configuration

To enable inbox layout for a list action, set display_layout.config.type to INBOX:

{
  "id": "list-orders",
  "action_name": "listOrders",
  "display_layout": {
    "config": {
      "type": "INBOX",
      "inboxConfig": {
        "getTool": {
          "toolId": "get-order"
        },
        "title": {
          "template": "{{$.reference}}"
        }
      }
    }
  }
}

The inbox layout requires a getTool link. This is the get action that loads the full record when an item is selected.

List panel configuration

The list panel shows a scrollable list of items. Each item displays a title and optional description, with support for additional context and avatars.

Title and description

Configure what appears in each list item using string templates:

{
  "inboxConfig": {
    "title": {
      "template": "Order #{{$.reference}}"
    },
    "description": {
      "template": "{{$.customer.name}} - {{$.status}}"
    }
  }
}

The title is the primary text for each item, typically a reference number, name, or identifier. The description provides secondary information and appears below the title in a smaller, muted style.

Context field

The contextField displays information on the right side of each item. Use it for dates, amounts, or status indicators:

{
  "inboxConfig": {
    "title": {
      "template": "{{$.reference}}"
    },
    "contextField": {
      "template": "{{$.totalAmount}}"
    }
  }
}

Avatars

Enable avatars to show images or initials alongside each item:

{
  "inboxConfig": {
    "title": {
      "template": "{{$.customer.name}}"
    },
    "avatarEnabled": true,
    "avatarUrl": {
      "template": "{{$.customer.avatarUrl}}"
    },
    "avatarFallback": {
      "template": "{{$.customer.initials}}"
    }
  }
}

Detail panel configuration

When you select an item from the list, the detail panel loads the full record using the linked get action. The detail panel displays the record using the get tool's configuration.

Linking the get action

The getTool field specifies which get action to use:

{
  "inboxConfig": {
    "getTool": {
      "toolId": "get-order"
    }
  }
}

When a user selects an item, the inbox layout:

1. Reads the item's id field from the list response
2. Calls the linked get action with that id
3. Displays the result in the detail panel

The detail panel inherits all configuration from the linked get tool, including sections, field visibility, and embedded tools.

Configuration options

Here's the complete set of inbox configuration options:

Example: Order inbox

Here's a complete configuration for an order processing inbox:

model Order {
  fields {
    reference Text @unique
    status OrderStatus
    customer Customer
    totalAmount Decimal
    placedAt Timestamp
  }
 
  actions {
    get getOrder(id)
    list listOrders(status?)
  }
}
 
enum OrderStatus {
  Pending
  Processing
  Shipped
  Delivered
}

{
  "id": "list-orders",
  "action_name": "listOrders",
  "name": "Order Inbox",
  "display_layout": {
    "config": {
      "type": "INBOX",
      "inboxConfig": {
        "getTool": {
          "toolId": "get-order"
        },
        "title": {
          "template": "Order #{{$.reference}}"
        },
        "description": {
          "template": "{{$.customer.name}}"
        },
        "contextField": {
          "template": "{{$.totalAmount}}"
        },
        "avatarEnabled": false
      }
    }
  },
  "filter_config": {
    "quick_search_field": "$.where.reference.contains"
  }
}

{
  "id": "get-order",
  "action_name": "getOrder",
  "name": "View Order",
  "title": "Order #{{$.reference}}",
  "sections": [
    {
      "name": "details",
      "title": "Order Details",
      "display_order": 1,
      "visible": true
    },
    {
      "name": "customer",
      "title": "Customer Information",
      "display_order": 2,
      "visible": true
    }
  ],
  "response": {
    "$.reference": {
      "section_name": "details",
      "display_order": 1
    },
    "$.status": {
      "section_name": "details",
      "display_order": 2
    },
    "$.totalAmount": {
      "section_name": "details",
      "display_order": 3
    },
    "$.placedAt": {
      "section_name": "details",
      "display_order": 4
    },
    "$.customer.name": {
      "section_name": "customer",
      "display_order": 1
    }
  },
  "entry_activity_actions": [
    {
      "tool_id": "update-order",
      "display_order": 1
    }
  ]
}

With this configuration, users see a list of orders on the left. Selecting an order displays its full details on the right, organised into sections with action buttons for updating the order.