Help Center > AI Prompts & Classification

AI Prompts & Classification Guide

Estimated reading time: 7 minutes

Table of Contents

Quick Start

The Email Classification SaaS uses Google Gemini 1.5 Flash, a state-of-the-art AI model, to intelligently classify your emails into categories. You can optionally customize the AI's behavior through a System Prompt that provides business-specific context.

What You'll Learn How the AI classification process works, when and how to customize system prompts, and best practices for optimizing classification accuracy through prompt engineering.

Key Concepts

Do I Need a Custom System Prompt?

Most users do NOT need a custom system prompt. The default prompt is optimized for general email classification and works well for 90% of use cases.

Use Default Prompt If:

Consider Custom Prompt If:

Start Simple Begin with the default prompt. Only add customization if you observe specific classification issues. Test custom prompts with sample emails before deploying.

How AI Classification Works

Understanding the classification workflow helps you write effective custom prompts and troubleshoot issues.

Step-by-Step Classification Process

  1. Email Arrives: Gmail webhook triggers when new email arrives in your inbox
  2. Email Fetching: System retrieves email content (subject, sender, body) via Gmail API
  3. Content Preprocessing:
    • HTML tags removed (if configured in Global Rules)
    • Email signatures stripped (if configured)
    • Quoted text removed (if configured)
    • Whitespace normalized (if configured)
    • Body truncated to configured length (default: 4000 chars)
  4. Prompt Construction:
    • System prompt (custom or default) prepended
    • All enabled categories with descriptions added
    • Email content (sender, subject, body) included
    • VIP sender status noted (if applicable)
    • Classification instructions added
  5. AI Processing: Gemini 1.5 Flash analyzes email and returns:
    • Categories (1 or more, depending on multi-classification settings)
    • Confidence scores (0-100% for each category)
    • Priority level (high/medium/low)
    • Action date (if detected, e.g., "due Friday")
    • Urgency date (for time-sensitive labels)
  6. Post-Processing:
    • Confidence thresholds checked (per-category and global)
    • Category conflicts resolved (higher confidence wins)
    • Required relationships enforced
    • Max classifications limit applied
  7. Actions Execution:
    • Gmail labels created/applied
    • Automated actions triggered (auto-draft, mark important, archive, webhook)
    • Urgency labels applied (if dates detected within thresholds)
    • Notifications sent (if configured)
Processing Time Typical email classification takes 1-3 seconds end-to-end. Complex emails with multiple categories may take 3-5 seconds. Gmail labels appear within 5-10 seconds of email arrival.

What the AI Sees

The complete classification prompt sent to Gemini includes:

[SYSTEM PROMPT - Your custom prompt or default] Available Categories: 1. Category Name: Description, keywords, priority 2. Category Name: Description, keywords, priority ... (all enabled categories) Email to Classify: From: sender@example.com Subject: Email subject line Body: Email content (truncated to configured length) [VIP Sender: Yes/No] [Trusted Domain: Yes/No] Instructions: Classify this email into one or more categories. Return: - categories: array of category names - confidence: confidence score for each (0-100) - priority: high/medium/low - action_date: detected deadline (YYYY-MM-DD) - urgency_date: time-sensitive deadline (YYYY-MM-DD)

Your custom system prompt appears at the top and provides context that influences all subsequent analysis.

System Prompts Overview

Accessing System Prompt Configuration

Location: Global Rules page → Section 10: System Prompt (scroll to bottom)

Technical Details

Property Value
Character Limit 1000 characters (default), up to 5000 for admin users
Storage Path tenant_users/{tenant_id}_{email}/config/prompts
Backend Use Loaded in main.py (lines 656-661), prepended to classification prompt
Fallback Behavior If empty/not set, system uses default optimized prompt
Truncation Automatically truncated if exceeds limit (lines 683-686)
Apply To ALL emails processed (global setting)

When Prompts Take Effect

Writing Effective Prompts

Prompt Writing Principles

1. Provide Context, Not Instructions

The AI already knows how to classify emails. Your prompt should provide business context that helps it understand your specific needs.

✅ DO: Provide Context

"You are classifying emails for a legal firm. Court-related emails are high priority. Client communications include case updates, billing, and consultation requests."

❌ DON'T: Give Instructions

"Classify emails into categories. Look at the subject line and body. Return a confidence score between 0 and 100."

2. Be Specific About Terminology

Define industry-specific terms or acronyms the AI might not understand.

✅ DO: Define Terms

"'Sprint' refers to our 2-week development cycles. 'Standup' means daily team meeting. 'PR' means Pull Request (code review)."

❌ DON'T: Assume Knowledge

"Classify sprint-related PRs as development work."

3. Explain Prioritization Rules

If certain email types should always be high/low priority, state this explicitly.

✅ DO: Set Priorities

"Emails from clients are always high priority. Internal team updates are medium priority. Automated reports are low priority unless they contain error keywords."

❌ DON'T: Be Vague

"Some emails are more important than others."

4. Keep It Concise

Aim for 3-5 bullet points (200-500 characters). Longer prompts consume API tokens and may dilute key points.

Good Length Example (322 characters)

You are classifying emails for a software consulting firm. - "Client Projects" = active billable client work - "Sales" = prospective client inquiries and proposals - "Internal" = team communication, HR, company updates - Prioritize emails from current clients over leads - Deadline mentions = high priority

5. Use Examples When Helpful

If a category is ambiguous, provide 1-2 examples of emails that belong in it.

Example with Context

Personal finance email classification: - "Investments" includes 401k statements, brokerage alerts, stock notifications - "Banking" covers checking/savings transactions, alerts, statements - "Bills" are recurring payments (utilities, subscriptions, insurance) - "Shopping" includes order confirmations, shipping updates, receipts

Prompt Structure Template

[Context sentence: What type of emails are being classified] [Business-specific definitions:] - Term 1: Definition - Term 2: Definition - Category clarification: What belongs in this category [Prioritization rules:] - High priority: X, Y, Z - Low priority: A, B, C [Special handling (if needed):] - Edge case clarification - Deadline detection notes

Prompt Examples by Industry

Example 1: Software Development Agency

Use Case: Development agency with client projects and internal ops

You are classifying emails for a software development consulting firm. Business context: - "Client Projects" = active billable work, project updates, deliverables - "Sales/Prospecting" = new client inquiries, proposals, discovery calls - "Internal" = team meetings, HR, company announcements - "Technical" = infrastructure alerts, dependency updates, CI/CD Priority rules: - Client emails > internal emails > automated alerts - Mentions of "urgent", "down", "broken" = high priority - Newsletters and marketing = low priority

Example 2: Legal Practice

Use Case: Law firm with court cases, client communications, billable hours

You are classifying legal emails for a law firm. Critical priorities: - Court-related emails (filings, hearings, depositions) = always high priority - Client case communications = high priority, billable - Internal admin (billing, HR, operations) = medium priority - Marketing and CLE (continuing education) = low priority Terminology: - "Discovery" = evidence exchange process - "Motion" = formal court request - "Deposition" = sworn witness testimony - All court deadlines are time-sensitive

Example 3: E-commerce Business

Use Case: Online store with customer support, operations, marketing

You are classifying emails for an e-commerce business. Category definitions: - "Customer Support" = order issues, returns, product questions - "Operations" = supplier emails, inventory, shipping/logistics - "Marketing" = campaign performance, partnerships, promotions - "Financial" = payment processing, invoices, accounting Priority: - Customer complaints or negative feedback = high priority - Order fulfillment issues = high priority - Marketing analytics and reports = low priority - Automated system notifications = low priority unless "error"

Example 4: Freelance Consultant

Use Case: Solo consultant managing multiple clients and personal life

Personal email classification for freelance consulting. Work categories: - "Active Clients" = current project communications (high priority) - "Prospective Clients" = new inquiries, proposals (medium priority) - "Admin" = contracts, invoicing, taxes (medium priority) Personal categories: - "Family/Friends" = personal relationships (high priority) - "Finance" = banking, investments, bills (review needed) - "Travel" = bookings, confirmations, itineraries (time-sensitive) - "Newsletters" = subscriptions and marketing (low priority)

Example 5: Academic/Research

Use Case: University professor managing research, teaching, administration

You are classifying emails for an academic researcher and professor. Categories: - "Research" = paper submissions, peer reviews, conference notifications - "Teaching" = student questions, grading, course materials - "Grants/Funding" = grant applications, funding opportunities, budget - "Administration" = faculty meetings, university announcements - "Collaborations" = joint research projects, co-author communications Priority: - Student emails during semester = high priority - Grant deadlines = high priority (time-sensitive) - Conference deadlines = medium priority - General announcements = low priority

Example 6: Healthcare Practice

Use Case: Medical practice with patient care, insurance, administration

You are classifying emails for a medical practice. IMPORTANT: Never process emails containing patient medical information. This system is for administrative classification only. Categories: - "Patient Scheduling" = appointments, reminders, cancellations - "Insurance" = claims, authorizations, billing inquiries - "Pharmacy" = prescription refills, medication questions - "Administrative" = staff communications, facility management - "Medical Supplies" = equipment, inventory, vendors Priority: - Urgent patient needs = high priority - Insurance claim issues = medium priority - Routine scheduling = low priority

Best Practices

Testing & Iteration

1. Start with Default, Measure Baseline

  1. Use default prompt for 3-5 days
  2. Note average confidence score in Overview Dashboard
  3. Identify specific misclassification patterns
  4. Document which categories have accuracy issues

2. Write Draft Prompt

  1. Focus on business context for problematic categories
  2. Keep under 500 characters initially
  3. Use the structure template from this guide
  4. Review for clarity and conciseness

3. Test with Sample Emails

  1. Save draft prompt in Global Rules
  2. Send 5-10 test emails covering different categories
  3. Check Gmail labels within 30 seconds
  4. Review Telegram notifications (if enabled)
  5. Compare results to baseline

4. Monitor & Refine

  1. Track average confidence for 3-5 days
  2. Note any improvement or degradation
  3. Refine prompt if needed (add/remove context)
  4. Repeat testing cycle
A/B Testing Test prompts during low-volume periods (weekends). This lets you quickly assess impact without affecting important work emails. Compare weekend classification accuracy with and without custom prompt.

Common Pitfalls to Avoid

Pitfall Why It's a Problem Solution
Over-explaining Long prompts consume tokens, dilute key points Keep under 500 chars, focus on essentials
Giving AI instructions AI already knows how to classify Provide context, not process instructions
Conflicting with categories Prompt contradicts category descriptions Ensure prompt aligns with Categories page definitions
Too many edge cases Prompt becomes confusing with exceptions Handle edge cases via category rules, not prompt
Not testing Prompt may hurt accuracy instead of helping Always test with sample emails before deploying

Optimization Strategies

If Confidence Is Too Low (<80%)

If Specific Categories Underperform

If Priority Detection Is Wrong

Maintenance Schedule

FAQs & Troubleshooting

Q: Will a custom prompt improve my classification accuracy?

A: Maybe. If you have specialized terminology or business context, yes. If your categories are already clear and general-purpose, a custom prompt may not help. Always test and measure impact before committing.

Q: How long should my system prompt be?

A: 200-500 characters (3-5 bullet points) is ideal. Longer prompts consume API tokens and may dilute important context. If you're hitting the 1000 character limit, your prompt is too long.

Q: Can I use different prompts for different categories?

A: No, the system prompt is global (applies to all emails). However, you can include category-specific context in the prompt (e.g., "'Client Projects' includes X, Y, Z"). Per-category customization happens via category descriptions on the Categories page.

Q: What happens if my prompt conflicts with category descriptions?

A: Category descriptions take precedence in the final classification prompt. Ensure your system prompt provides general context that complements (not contradicts) your category definitions.

Q: My custom prompt made classification worse. Why?

A: Common causes: (1) Prompt is too long/confusing, (2) Prompt contradicts category descriptions, (3) Prompt gives instructions instead of context, (4) Prompt is too vague/general. Try reverting to default and starting with a simpler prompt focused on specific issues.

Q: Can I see the full prompt sent to Gemini?

A: The complete prompt is not exposed in the UI, but you can see the structure in this guide's "How AI Classification Works" section. Your system prompt is prepended to categories, email content, and classification instructions.

Q: Do I need to include classification instructions in my prompt?

A: No. The system automatically adds classification instructions (return categories, confidence, priority, dates). Your prompt should only provide business context. Adding redundant instructions wastes characters and tokens.

Q: How often should I update my system prompt?

A: Quarterly or when significant business changes occur (new service offerings, organizational changes, new category additions). Most prompts remain stable for months once optimized.

Q: Can I use markdown formatting in my prompt?

A: Basic formatting (bullet points with "-", line breaks) is supported and recommended for clarity. Avoid complex markdown (headers, links, tables) as it consumes characters unnecessarily.

Q: What's the difference between the system prompt and category descriptions?

A: The system prompt provides overarching business context that applies to all classifications. Category descriptions define specific criteria for each category. Think of system prompt as "company overview" and category descriptions as "job descriptions".

Q: My prompt is exactly 1000 characters. Will it be truncated?

A: At exactly 1000 characters, it should not be truncated. Truncation only occurs if the prompt exceeds the limit. However, leave some buffer (aim for 950 characters max) to ensure no accidental truncation.

Q: Can I request a higher character limit for my prompt?

A: Admin users can configure limits up to 5000 characters. Contact support with your use case if you need a higher limit. However, most effective prompts are well under 500 characters.

Need More Help?
Back to Top