# ClearCafe / FreeScout — Agent Skill Guide

For AI agents managing email helpdesks via ClearCafe (powered by FreeScout). This guide covers API usage, common workflows, and best practices.

## Overview

ClearCafe is an email management system built on FreeScout (open-source helpdesk). It connects multiple email inboxes into a unified dashboard where conversations can be triaged, assigned, and responded to via API.

### Architecture

```
config.clearcafe.com          ← Orchestration layer (optional)
  AI triage, SOPs, routing       Auto-classifies incoming email
       │ manages
  ┌────┼──────────────┐
  ▼    ▼              ▼
Instance A  Instance B  Instance C   ← Each is a FreeScout install
                                        with its own mailboxes
```

Each FreeScout instance has:
*   Its own **API key** (passed via `X-FreeScout-API-Key` header)
*   Its own **user IDs** (the same person has different IDs on each instance!)
*   Its own **mailboxes** (email accounts connected to it)
*   Its own **conversations** (email threads)

## Authentication

All API calls use the `X-FreeScout-API-Key` header:

```bash
curl -s "https://<instance-domain>/api/conversations" \
  -H "X-FreeScout-API-Key: YOUR_API_KEY"
```

Each instance has a separate API key. Store them securely in `.env`.

## API Quick Reference

Full API Docs: [https://api-docs.freescout.net/](https://api-docs.freescout.net/)

| Action              | Method | Endpoint                        |
| ------------------- | ------ | ------------------------------- |
| List mailboxes      | GET    | `/api/mailboxes`                  |
| List conversations  | GET    | `/api/conversations`              |
| Get conversation    | GET    | `/api/conversations/{id}`         |
| Get threads         | GET    | `/api/conversations/{id}/threads` |
| Reply               | POST   | `/api/conversations/{id}/threads` |
| Update conversation | PUT    | `/api/conversations/{id}`         |
| List users          | GET    | `/api/users`                      |
| List customers      | GET    | `/api/customers`                  |

### Common Filters

*   **Active**: `GET /api/conversations?status=active`
*   **By Mailbox**: `GET /api/conversations?status=active&mailbox=1`
*   **By Assignee**: `GET /api/conversations?status=active&assignedTo=5`
*   **Pagination**: `GET /api/conversations?status=active&page=2` (50/page)
*   **Status values**: `active` | `pending` | `closed` | `spam`

## Core Workflows

### 1. Reply to a Conversation

**endpoint**: `POST /api/conversations/{id}/threads`

```json
{
  "type": "message",
  "body": "<p>Your reply in HTML</p>",
  "status": "active"
}
```

⚠️ **Warning**: Body must be HTML, not plain text.

### 2. Internal Note (not visible to customer)

**endpoint**: `POST /api/conversations/{id}/threads`

```json
{
  "type": "note",
  "body": "<p>Internal note</p>"
}
```

### 3. Assign a Conversation

**endpoint**: `PUT /api/conversations/{id}`

```json
{
  "assignTo": 5
}
```

### 4. Change Status

**endpoint**: `PUT /api/conversations/{id}`

```json
{
  "status": "closed"
}
```

## Thread Types

| Type       | Meaning                                |
| :--------- | :------------------------------------- |
| `customer` | Message FROM customer (awaiting reply) |
| `message`  | Reply FROM agent (sent to customer)    |
| `note`     | Internal note (invisible to customer)  |
| `lineitem` | Status change log                      |

## "Awaiting Reply" Detection

Check `waitingSince.type`:

*   `"customer"` → Customer is waiting for us to reply
*   Last thread type `"customer"` → We need to respond

### ⚠️ Multi-Instance Gotcha

User IDs are different across instances. Same person = different ID per instance.
**Always query `/api/users` per instance to build a mapping.**

## Deep Links (Mandatory)

Every conversation reference must include: `https://<instance>/conversation/<ID>`

✅ `#12345` — [https://app.clearcafe.com/conversation/12345](https://app.clearcafe.com/conversation/12345)
❌ `#12345` — needs attention (no link!)

## Config API (Orchestration Layer)

Uses xAI for auto-triage of incoming emails. For detailed SOPs and API guide for `config.clearcafe.com`, please refer to [skill_config.md](/skill_config.md).

```bash
GET  /api/agent/config          # System status
GET  /api/agent/decisions       # Recent triage decisions
GET  /api/agent/sops            # Routing rules (100+ SOPs)
POST /api/agent/sops            # Create/update SOP
```

## Best Practices

1.  **Scan 2x/day** (morning + evening) — don't spam channels.
2.  **Flag stale items** older than 48 hours.
3.  **Always use HTML** in reply bodies.
4.  **Check pagination** — default 50/page, fetch all pages.
5.  **Use notes** for internal agent context.
6.  **Deep link every reference** — no exceptions.
7.  **Maintain user ID mapping** per instance.

## Common Mistakes

| Mistake                       | Fix                             |
| ----------------------------- | ------------------------------- |
| Same user ID across instances | Per-instance ID mapping         |
| Plain text replies            | Always HTML tags                |
| Not paginating                | Check `totalPages`              |
| No deep links                 | `/conversation/<ID>` always     |
| Scanning too often            | 2-3x/day max                    |
| Reply without reading thread  | Always read full thread first   |

---
v1.0 — Feb 18, 2026 | Janice Jung