Estimated reading time: 8 minutes
The Categories page is where you define the email categories that the AI will use to classify and organize your Gmail inbox. Well-designed categories are the foundation of effective email automation and intelligent inbox organization.
Categories are configured through a comprehensive 5-tab modal that covers all aspects of email classification, automated actions, and category relationships.
Use the toggle switch on each category card to enable or disable classification:
Use Case: Temporarily disable seasonal categories (e.g., "Holiday Shopping") during off-season without deleting the configuration.
Categories are configured through 5 tabs containing 16 total configuration fields. All fields are stored in Firestore at tenant_users/{tenant_id}_{user_email}/config/categories and loaded by the email processor during classification.
Type: Text (required)
Purpose: Internal identifier for the category
Best Practice: Use clear, concise names (2-4 words). Examples: "Client Projects", "Team Updates", "Financial Documents"
Backend Use: Sent to Gemini AI in classification prompt
Type: Textarea (required)
Purpose: Detailed explanation of what emails belong in this category
Best Practice: Be specific and include examples. The AI reads this description when classifying emails.
Example: "Emails from clients regarding active projects, including status updates, deliverable requests, feedback, and project-related questions."
Backend Use: Critical for AI classification accuracy; included in Gemini prompt
Type: Color picker
Purpose: Color applied to Gmail label for visual identification
Options: Choose from Gmail's standard label colors
Best Practice: Use consistent color schemes (e.g., red for urgent, blue for informational, green for personal)
Backend Use: Applied when creating/updating Gmail labels via label_service.py
Type: Text (optional)
Purpose: Custom name for the Gmail label (if different from category name)
Default: Uses category name if not specified
Use Case: Shorten long category names for Gmail (e.g., "Client Communications and Project Updates" → "Client Projects")
Type: Toggle (boolean)
Purpose: Enable or disable this category for classification
Default: Enabled (true)
Backend Use: Email processor skips disabled categories during classification
Type: Comma-separated list
Purpose: Keywords that help the AI identify emails for this category
Example: "project update, deliverable, milestone, deadline, status report"
Backend Use: Included in Gemini classification prompt as hints
Note: Keywords guide the AI but don't guarantee classification (AI considers full email context)
Type: Number (0-100)
Purpose: Minimum confidence score required to apply this category
Default: 70 (70%)
Range:
Backend Use: Checked in main.py during classification; categories below threshold are not applied
Type: Dropdown (high/medium/low)
Purpose: Default priority for emails in this category
Use Case: Automatically prioritize categories like "Client Communications" (high) vs. "Newsletters" (low)
Backend Use: Used for priority label creation if enabled in Global Rules
Automated actions triggered when an email is classified into this category.
Type: Checkbox (boolean)
Purpose: Automatically create a draft reply using AI when email is classified
Backend Use: Triggers draft creation in main.py (line 1381+)
Requirements: Confidence must meet threshold in Global Rules → Processing Rules
Type: Checkbox (boolean)
Purpose: Apply Gmail "Important" flag to emails in this category
Backend Use: Gmail API call to star/flag email
Use Case: Ensure high-priority categories stand out in Gmail
Type: Checkbox (boolean)
Purpose: Automatically archive emails after labeling (remove from inbox)
Backend Use: Gmail API call to remove INBOX label
Use Case: Keep inbox clean by auto-archiving newsletters, receipts, notifications
Type: Text (URL)
Purpose: HTTP endpoint to receive notification when email is classified into this category
Format: Must be valid HTTPS URL
Payload: JSON with email metadata, category, confidence score
Backend Use: webhook_service.py sends POST request
Type: Email address
Purpose: Automatically forward emails in this category to specified email address
Status: ⚠️ Future feature (not yet deployed)
Planned Use: Forward specific categories to team members or external systems
Define how categories interact with each other in multi-classification scenarios.
Type: Multi-select dropdown
Purpose: Categories that must be applied together with this category
Example: "Action Required" might be required with "Client Communications"
Backend Use: Enforced during classification in ai_classifier.py
Type: Multi-select dropdown
Purpose: Categories that cannot be applied simultaneously with this category
Example: "Spam" conflicts with "Important" and "Client Communications"
Backend Use: Higher-confidence category wins; conflicting lower-confidence category is skipped
Displayed Data:
Data Source: Aggregated from analytics integration with daily summaries
Use Case: Monitor category performance to identify underperforming or overused categories
Multi-category classification allows the AI to apply multiple categories to a single email when appropriate. This feature is enabled in Global Rules → Multi-Classification Rules.
Most users achieve optimal results with 8-12 categories. This provides sufficient organization granularity without overwhelming the AI or creating overlapping definitions.
Design categories so emails clearly belong to one primary category. Use multi-classification sparingly for special cases (e.g., "Urgent" as a secondary modifier category).
The AI reads your category descriptions. More specific descriptions lead to higher confidence scores:
Include 5-15 relevant keywords per category. Focus on terms commonly found in emails for that category:
Use consistent color schemes to make Gmail labels intuitive:
| Color | Suggested Use | Example Categories |
|---|---|---|
| Red | Urgent/Important | Action Required, Urgent, Alerts |
| Yellow/Orange | Needs Attention | Client Communications, Follow-Up |
| Blue | Informational | Newsletters, Updates, FYI |
| Green | Personal/Positive | Personal, Confirmations, Receipts |
| Purple | Administrative | HR, Financial, Legal |
| Gray | Low Priority | Spam, Automated, Notifications |
A: Start with 8-12 categories for most use cases. Fewer than 5 provides insufficient organization; more than 15 can lead to overlapping definitions and lower confidence scores. Use the system defaults as a starting point, then customize based on your specific email patterns.
A: Changes apply only to new emails processed after saving. Existing labeled emails are not retroactively reclassified. Gmail labels remain on old emails unless you manually remove them in Gmail.
A: No, each category must have a unique Gmail label name. If you try to use a duplicate name, the system will automatically append a number (e.g., "Work (2)"). Use the "Gmail Label Name" field to customize label names while keeping category names distinct.
A: Check the following:
A: Each category is evaluated independently. If an email scores 85% for "Client Communications", 78% for "Financial", and 90% for "Action Required", all three categories will be applied IF their individual confidence thresholds are met and max classifications setting allows it (configured in Global Rules).
A: Multi-classification allows categories to be applied together if they meet thresholds. "Required With" FORCES categories to be applied together even if one doesn't meet its threshold. For example, if "Urgent" is required with "Action Required", applying "Action Required" will also apply "Urgent" automatically.
A: Currently, categories are stored in Firestore at tenant_users/{tenant_id}_{user_email}/config/categories. You can access them via the API, but there's no built-in import/export UI feature yet. Contact support if you need to bulk configure categories across multiple users.
A: Send yourself a test email that clearly matches the category criteria. Check Gmail within 30-60 seconds to see if the label appears. Review the Overview Dashboard to confirm the classification was recorded. If using Telegram notifications, you'll receive an instant notification when the email is classified.
A: The AI applies the category with the higher confidence score and skips the conflicting category. For example, if "Work" scores 88% and "Personal" scores 82%, and they conflict, only "Work" is applied. This prevents contradictory classifications.
A: Yes, emoji are supported in category names and will appear in Gmail labels. Some users prefix categories with emoji for visual distinction (e.g., "⚡ Urgent", "📧 Newsletters", "💼 Work"). However, ensure emoji render correctly in your Gmail interface.
A: Auto-draft requires:
A: Keywords are hints sent to the AI but are not strict filters. The AI considers keywords along with the full email content, sender, subject, and category description. Think of keywords as helping the AI understand what terms are relevant to this category, not as required match criteria.