Help Center > Settings & Configuration

Settings & Configuration Guide

Estimated reading time: 6 minutes

Table of Contents

Quick Start

The Settings page is your control center for managing Gmail connection, Telegram notifications, watch renewal, and system enable/disable. Configure these settings once during initial setup, then return periodically for maintenance.

What You'll Configure Gmail OAuth connection, Gmail watch monitoring, Telegram notification integration, and global system enable/disable control.

Initial Setup Checklist (15 minutes)

  1. Connect Gmail Account: Authorize OAuth permissions (required for classification)
  2. Verify Watch Status: Confirm Gmail watch is active and monitoring inbox
  3. Configure Telegram (Optional): Set up bot token and chat ID for notifications
  4. Enable System: Toggle system on to begin processing emails
  5. Send Test Email: Verify end-to-end functionality

Settings Page Sections

Section Purpose Required?
Account Information View email, tenant ID, account status Read-only
Gmail Connection OAuth authentication and authorization ✅ Required
Gmail Watch Monitor watch status, renew when needed ✅ Required (auto-managed)
Telegram Notifications Configure instant notifications and daily summaries Optional
System Control Enable/disable email processing ✅ Required

Account Information

This section displays read-only information about your account and tenant configuration.

Displayed Fields

Email Address

The Gmail account connected to this classification system. This email receives classified emails and is used for OAuth authentication.

Example: you@gmail.com or you@yourdomain.com

Tenant ID

Your unique tenant identifier in the multi-tenant system. Used for data isolation and API authentication.

Format: personal-yourname or business-companyname

Use Case: Reference this ID when contacting support or accessing API endpoints.

Account Status

Current status of your tenant account.

Status Values:

  • Active - Account operational, classification running
  • Inactive - Account disabled, no email processing
  • Pending - Account awaiting approval or setup completion

Gmail Connection & OAuth

Gmail connection uses OAuth 2.0 for secure authentication. This grants the system permission to read your emails, create labels, and send automated draft replies.

Connecting Your Gmail Account

First-Time Setup Required You must connect Gmail before any email classification can occur. Without an active Gmail connection, the system operates in demo mode with sample data.

Step-by-Step OAuth Flow

  1. Click "Connect Gmail Account" Button

    Located in the Gmail Connection section of Settings page

  2. Google Login Page

    A Google OAuth page opens in a new window. Log in with your Gmail account if not already logged in.

  3. Review Permissions

    Google displays the permissions requested by the application:

    • Read your emails: Required to analyze email content for classification
    • Manage labels: Required to create and apply Gmail labels
    • Send emails: Required to create draft replies (if auto-draft enabled)
    • Manage Gmail settings: Required to set up Gmail watch for real-time notifications
  4. Grant Permissions

    Click "Allow" to grant permissions. The system cannot function without these permissions.

  5. Redirect & Confirmation

    You'll be redirected back to the dashboard. A success message confirms the connection.

  6. Automatic Watch Setup

    The system automatically establishes a Gmail watch to receive real-time email notifications.

Connection Successful Once connected, your Gmail watch status should show Connected within 30 seconds. You can now enable the system and begin processing emails.

OAuth Token Management

Token Storage

OAuth tokens are securely stored in Firestore at:

tenants/{tenant_id}/users/{email}/oauth2_credentials

Token Expiration

Disconnecting Gmail

To disconnect your Gmail account:

  1. Click "Disconnect Gmail" button (appears when connected)
  2. Confirm disconnection in the dialog
  3. System stops processing emails immediately
  4. Existing labels remain in Gmail but no new labels are created
Impact of Disconnecting Disconnecting stops all email processing. Your configuration (categories, rules) is preserved. Reconnecting the same account resumes processing with existing configuration.

Permissions & Security

Data Privacy Your emails are processed in memory and not permanently stored. Only classification metadata (sender, subject, category, confidence) is saved to Firestore. Full email content is sent to Gemini AI for classification, then discarded. See our Privacy Policy for details.

Required Permissions Explained

Permission Scope Used For
Read emails gmail.readonly Fetching email content for AI classification
Manage labels gmail.labels Creating categories as Gmail labels, applying labels to emails
Send emails gmail.send Creating draft replies (auto-draft feature)
Modify emails gmail.modify Marking important, archiving, marking read

Gmail Watch Management

Gmail watch is a push notification system that alerts the Email Classification SaaS when new emails arrive. This enables real-time classification (emails classified within 5-10 seconds of arrival).

How Gmail Watch Works

  1. System establishes a watch on your Gmail inbox via Gmail API
  2. When new email arrives, Gmail sends notification to Google Pub/Sub topic
  3. Pub/Sub triggers the email-processor-saas Cloud Function
  4. Cloud Function fetches email content and performs classification
  5. Gmail labels are applied within 5-10 seconds of email arrival

Watch Status Indicators

Connected & Active

Meaning: Watch is established and monitoring your inbox. Emails will be classified in real-time.

Expiration: Displays when the watch will expire (typically 7 days from creation)

Action: None required. System auto-renews watches before expiration.

Expiring Soon

Meaning: Watch expires in less than 24 hours.

Expiration: Shows exact expiration timestamp

Action: Click "Renew Watch" button to extend for another 7 days, or wait for automatic renewal.

Not Connected

Meaning: Watch is not established or has expired. No emails are being processed.

Cause: Gmail not connected, watch expired, or OAuth token revoked

Action: Connect Gmail (if disconnected) or click "Renew Watch" (if expired)

Watch Renewal

Automatic Renewal

The watch_renewal Cloud Function runs daily at midnight to automatically renew watches expiring within 48 hours. You don't need to manually renew in most cases.

Manual Renewal

If you need to renew immediately:

  1. Navigate to Settings page
  2. Find Gmail Watch section
  3. Click "Renew Watch" button
  4. Watch extends for another 7 days
  5. New expiration date displays immediately
Renewal Best Practices Let the system handle renewals automatically. Only manual renew if: (1) You see "Expiring Soon" and want immediate renewal, (2) Watch expired and auto-renewal failed, (3) Support instructed you to renew manually.

Watch Troubleshooting

Watch Shows Disconnected Despite Gmail Connection

  1. Check OAuth token hasn't been revoked (Google Account → Security → Third-party apps)
  2. Click "Renew Watch" button to re-establish
  3. If fails, disconnect and reconnect Gmail
  4. Contact support if issue persists

Watch Expires Before Auto-Renewal

Rare, but can happen if watch_renewal function experiences errors. Solution:

  1. Click "Renew Watch" manually
  2. Check that watch expiration is now 7 days in the future
  3. Contact support to investigate auto-renewal failure

Email Notifications

Receive email notifications for important events directly in your inbox. Configure which events trigger notifications, set daily limits, and choose where notifications are sent.

Email Notifications are Optional and Disabled by Default You must explicitly enable email notifications in the Notifications section of the dashboard. All notification types are opt-in for your privacy and inbox control.

Setting Up Email Notifications

Enabling Email Notifications

  1. Navigate to Dashboard → Notifications
  2. Click + Add Notification
  3. Select Email from the notification type dropdown
  4. Configure your notification preferences (see below)
  5. Click Save Notification

Email Notification Types

Choose which events should trigger email notifications. You can enable multiple types:

Configuration Options

Notification Email Address (Optional)

By default, notifications are sent to your signup email address. You can optionally specify a different email address if you want notifications sent elsewhere (e.g., a dedicated notifications inbox).

Leave Blank for Default If you leave the notification email address field blank, notifications will be sent to your account email. Only fill this in if you want notifications sent to a different address.

Daily Notification Limit

Set a maximum number of email notifications to receive per day (10-100). This prevents notification overload on busy email days.

Per-Category Notifications

Enable notifications for specific email categories in the category management section:

  1. Go to Dashboard → Categories
  2. Edit the category you want notifications for
  3. Under Notifications & Forwarding, enable the notification toggle
  4. Save the category

Category notifications only work if:

Email Notification Format

Email notifications are sent from notifications@aiclassifier.tech and include:

Managing Notification Volume

Too Many Notifications?

Missing Notifications?

Disabling Email Notifications

To stop receiving email notifications:

  1. Go to Dashboard → Notifications
  2. Find the Email notification in the list
  3. Click Delete or Disable
  4. Confirm the action

Your configuration is saved, so you can re-enable notifications later without reconfiguring all settings.

Telegram Notifications

Receive instant notifications via Telegram when high-priority emails are classified, urgent deadlines are detected, or daily email summaries.

Telegram is Optional The email classification system works perfectly without Telegram. Notifications are a convenience feature for real-time alerts. Skip this section if you don't want Telegram integration.

Setting Up Telegram Notifications

Prerequisites

Step 1: Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Start a conversation with BotFather
  3. Send command: /newbot
  4. Follow prompts to name your bot (e.g., "My Email Classifier Bot")
  5. BotFather returns a Bot Token (looks like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
  6. Copy and save this token - you'll enter it in Settings page
Keep Your Bot Token Secret Anyone with your bot token can send messages through your bot. Never share it publicly or commit it to version control.

Step 2: Get Your Chat ID

  1. Search for your newly created bot in Telegram (use the username from BotFather)
  2. Start a conversation with your bot
  3. Send any message to the bot (e.g., "Hello")
  4. Open this URL in your browser (replace YOUR_BOT_TOKEN):
    https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
  5. Look for "chat":{"id":123456789} in the JSON response
  6. The number is your Chat ID (can be positive or negative)
  7. Copy and save this Chat ID

Step 3: Configure in Settings Page

  1. Navigate to Settings → Telegram Notifications
  2. Paste Bot Token in the first field
  3. Paste Chat ID in the second field
  4. Click "Save Telegram Configuration"
  5. System sends a test message to verify connection
  6. Check Telegram for confirmation message
Configuration Successful If you receive a test message in Telegram, configuration is complete. You'll now receive notifications based on your Global Rules → Notification Settings configuration.

Notification Types

Configure which events trigger Telegram notifications in Global Rules → Section 8: Notification Settings. Options include:

Telegram Troubleshooting

Not receiving any notifications?

Check: (1) Bot token and chat ID are correct in Settings, (2) You sent at least one message to your bot, (3) Notification types are enabled in Global Rules, (4) System is enabled in Settings, (5) Emails are actually being processed (check Overview Dashboard).

Getting error "Bot not found" when saving?

Bot token is incorrect. Double-check you copied the full token from BotFather (including the colon and everything after it).

Getting error "Chat not found"?

You haven't started a conversation with your bot yet. Open Telegram, search for your bot, and send it any message first. Then retry configuration.

Disabling Telegram Notifications

To stop receiving Telegram notifications without deleting your configuration:

  1. Go to Global Rules → Section 8: Notification Settings
  2. Uncheck all notification types
  3. Save configuration

To completely remove Telegram configuration:

  1. Go to Settings → Telegram Notifications
  2. Clear both Bot Token and Chat ID fields
  3. Click "Save Telegram Configuration"

System Control

The System Control section provides a master enable/disable toggle for all email classification processing.

Enable/Disable System

System Enabled

Meaning: Email classification is active. New emails will be processed and labeled.

Requirements: Gmail must be connected and watch must be active

Effect: All Cloud Functions process emails normally

System Disabled

Meaning: Email classification is paused. No emails will be processed.

Effect: Cloud Functions exit early when checking system status

Use Case: Temporarily pause classification while reconfiguring categories

When to Disable System

Emails Are Not Queued When system is disabled, emails arriving during that time will NOT be retroactively classified when you re-enable. The system only processes emails arriving after enabling.

Storage Location

System enabled/disabled status is stored at:

tenants/{tenant_id}/system_enabled

This is a tenant-wide setting (applies to all users in the tenant).

Best Practices

Initial Setup Workflow

  1. Configure Categories First (Demo Mode): Set up categories and rules before connecting Gmail
  2. Connect Gmail: Authorize OAuth and establish watch
  3. Set Up Telegram (Optional): Configure bot and chat ID
  4. Enable Notifications: Choose notification types in Global Rules
  5. Enable System: Turn on email processing
  6. Send Test Emails: Verify end-to-end functionality
  7. Monitor First Day: Check Overview Dashboard and Telegram for correct behavior

Security Best Practices

Maintenance Schedule

Frequency Task Estimated Time
Daily Review daily Telegram summary (if enabled) 1 minute
Weekly Check Overview Dashboard for classification health 2 minutes
Monthly Verify watch status, review Settings page 5 minutes
Quarterly Review OAuth permissions in Google Account, update categories/rules 15 minutes
As Needed Renew watch if expired, reconnect Gmail if revoked 5 minutes

Troubleshooting Decision Tree

Emails Not Being Classified?

  1. Check System Control: Is system enabled? → If no, enable it
  2. Check Gmail Connection: Status showing connected? → If no, reconnect Gmail
  3. Check Watch Status: Watch active? → If no, renew watch
  4. Check Categories: Are any categories enabled? → If no, enable categories
  5. Send test email → If still not working, check Telegram for error notifications or contact support

FAQs & Troubleshooting

Q: How often do I need to reconnect Gmail?

A: Once connected, Gmail OAuth should remain active indefinitely (unless you revoke access in Google Account settings). Access tokens expire hourly but are automatically refreshed using your refresh token. Reconnection is only needed if you manually revoke access or encounter authentication errors.

Q: What happens if my watch expires?

A: No new emails will be classified until the watch is renewed. The watch_renewal Cloud Function automatically renews watches daily (for those expiring within 48 hours), so expiration is rare. If it does expire, click "Renew Watch" in Settings to re-establish immediately.

Q: Can I use a Google Workspace account instead of Gmail?

A: Yes, Google Workspace accounts (yourname@yourdomain.com) work identically to personal Gmail accounts. The OAuth flow and permissions are the same. Your workspace admin must allow third-party app access for the Email Classification SaaS.

Q: Is my email content stored or logged?

A: No. Full email content is processed in memory for AI classification, then immediately discarded. Only metadata (sender, subject, category, confidence score, timestamps) is stored in Firestore. Email content is sent to Gemini AI for classification but not permanently stored by Google either. See Privacy Policy for full details.

Q: Can I use Telegram without creating a bot?

A: No, Telegram requires a bot for programmatic messaging. Creating a bot takes 5 minutes via @BotFather and is free. The bot is private to you unless you explicitly share it with others.

Q: What if I accidentally revoke Gmail access?

A: Simply reconnect Gmail in Settings. Your configuration (categories, rules, prompts) is preserved. Reconnecting re-establishes OAuth and watch. Classification resumes for new emails (old emails from the disconnected period are not retroactively classified).

Q: Can I connect multiple Gmail accounts?

A: One Gmail account per user. To classify multiple accounts, create separate user accounts in the same tenant (if your plan supports multiple users) or use separate tenants. Contact support for multi-account setup guidance.

Q: Why does watch expire every 7 days instead of lasting forever?

A: Gmail API limitation. Watches can be set for a maximum of 7 days and must be periodically renewed. Our watch_renewal function handles this automatically, so you don't need to manually renew unless auto-renewal fails.

Q: Can I disable Telegram notifications temporarily?

A: Yes, go to Global Rules → Section 8: Notification Settings and uncheck all notification types. Save configuration. This preserves your bot token/chat ID while stopping notifications. Re-enable notifications by checking the boxes again.

Q: What's the difference between disabling system vs. disconnecting Gmail?

A: Disabling system (System Control toggle) pauses classification but maintains Gmail connection and watch. Disconnecting Gmail revokes OAuth and removes watch entirely. Use disable for temporary pauses; use disconnect if you want to fully deauthorize the app.

Need More Help?
Back to Top