How to Use AI Email Triage

Video Tutorial

Watch this walkthrough to see how to configure AI Email Triage for your FreeScout mailbox.

Open video in new tab

📧 Step 1: Connect to FreeScout

To enable automatic email triage, you need to install the AI Triage module in your FreeScout mailbox.

A. Upload the FreeScout Module

1. Download the module: freescout_module.zip
2. Extract the zip file on your computer
3. Rename the extracted folder from freescout_module to AiTriage
4. Upload the AiTriage folder to your FreeScout server at:
   mikesinbox.clearcafe.com/Modules/AiTriage/
5. Make sure the folder structure on your FreeScout server looks like this:
   

   Modules/
   └── AiTriage/
       ├── Module.php
       ├── Listener.php
       ├── module.json
       └── README.md

B. Configure Environment Variables

Add these to your FreeScout .env file:

REPLIT_WEBHOOK_URL=https://config.clearcafe.com/webhook
WEBHOOK_SECRET=your_secret_key_here

C. Activate the Module

1. Log in to your FreeScout admin panel
2. Go to Manage → Modules
3. Find AI Triage in the list
4. Click Activate

D. Get FreeScout API Key

1. In FreeScout, go to Manage → API
2. Generate a new API token
3. Add it to your Replit environment variables as FREESCOUT_API_KEY

📊 Step 2: Using the Dashboard

Once connected, the AI will automatically process incoming emails. Here's what happens:

How It Works

1. Email Arrives: New conversation created in FreeScout
2. Webhook Sent: FreeScout module sends email data to this system
3. AI Analysis: Grok AI analyzes the email using your SOPs
4. Decision Made: AI assigns email, adds notes, sets status
5. Applied: Changes automatically applied in FreeScout
6. Review: You can review AI decisions in the dashboard

Dashboard Statistics

• ✓ Total Decisions: Number of emails processed
• ✓ Auto-Closed (%): Percentage of emails closed automatically
• ✓ High Confidence (%): Percentage of decisions with >80% confidence

✅ Step 3: Reviewing AI Decisions

Click "Review" on any decision to provide feedback:

1. Approve: AI made the right decision
2. Reject: AI made a mistake (provide correction)
3. Modify: Adjust the decision and provide guidance
4. Learn as SOP: Turn this decision into a new rule for future emails

📝 Step 4: Managing SOPs (Standard Operating Procedures)

SOPs teach the AI how to handle specific types of emails.

Creating a New SOP

1. Go to SOPs page
2. Fill in the trigger pattern (e.g., "password reset", "billing question")
3. Set the action: who to assign to, what status to set
4. Add Q&A to explain the reasoning
5. Click Add SOP

Example SOPs

👥 Step 5: User Management (Admins Only)

Control who can access the AI Email Triage system.

1. When someone logs in via RegardingWork SSO for the first time, they're marked as "pending"
2. Go to Users page to see all access requests
3. Click Approve to grant access or Reject to deny
4. Promote trusted users to Admin to let them manage other users

User Roles

• 👤 User: Can view dashboard, review decisions, manage SOPs
• 👑 Admin: Everything above + approve/reject users, promote to admin

⚙️ Required Environment Variables

Set these in Replit's Secrets (environment variables):

Variable	Description	Required
XAI_API_KEY	Your Grok AI API key	✓ Yes
FREESCOUT_API_KEY	FreeScout API token	✓ Yes
WEBHOOK_SECRET	Shared secret for webhook authentication (must match FreeScout)	✓ Yes
SECRET_KEY	Flask session encryption key	✓ Yes
FREESCOUT_BASE_URL	Your FreeScout URL (default: https://mikesinbox.clearcafe.com)	Optional

🧪 Step 6: Testing Your Setup

1. Test the Webhook

1. Go to /test/webhook
2. Click "Send Test Webhook"
3. Check that it appears in the dashboard

2. Test with Real Email

1. Create a test conversation in FreeScout
2. Check FreeScout logs: storage/logs/laravel.log
3. Verify the decision appears in this dashboard
4. Confirm the conversation in FreeScout was updated (assigned/notes/status)

🔧 Troubleshooting

Module Not Showing in FreeScout

• Verify folder name is exactly AiTriage (case-sensitive)
• Check file permissions are readable by web server
• Clear FreeScout cache: php artisan cache:clear

Webhook Not Firing

• Check storage/logs/laravel.log in FreeScout for errors
• Verify REPLIT_WEBHOOK_URL and WEBHOOK_SECRET in FreeScout .env
• Test webhook manually using /test/webhook

AI Not Making Decisions

• Verify XAI_API_KEY is set in environment variables
• Check workflow logs for errors
• Make sure you've seeded some SOPs (/seed)