Habits

Appearance

Email Ticket Routing ​

Intermediate
ai email support automation routing
Download email-ticket-routing.habit
Email Ticket Routing
Click to zoom
Email Ticket Routing

Fetch support emails via IMAP, classify each ticket with AI, and automatically route it to the right team inbox (support, sales, billing, feedback, spam, or urgent) via SMTP.

Email Ticket Routing is an automation that reads your Gmail inbox over IMAP, uses OpenAI to classify each incoming email into one of six categories (support, sales, billing, feedback, spam, or urgent) and forwards it to the correct team inbox via SMTP : no manual triage needed.

What it does ​

  • Email fetching : Connects to Gmail via IMAP and retrieves unread messages with fetch-emails
  • AI classification : Passes each email to OpenAI for category detection (support / sales / billing / feedback / spam / urgent) and priority scoring via analyze-ticket
  • Team routing : Resolves the correct SMTP credentials for the target team and forwards the ticket via route-category and send-email
  • Full pipeline : ticket-routing orchestrates the entire fetch → analyze → assign flow; assign-ticket handles the per-ticket assignment steps

Environment variables (.env / keyring on apps) ​

VariablePurpose
HABITS_OPENAI_API_KEYOpenAI API key for ticket classification
HABITS_GMAIL_IMAP_HOSTIMAP host (e.g. imap.gmail.com)
HABITS_GMAIL_IMAP_PORTIMAP port (typically 993 for SSL)
HABITS_GMAIL_IMAP_USERGmail address to read incoming tickets from
HABITS_GMAIL_IMAP_APP_PASSWORDGmail App Password for the IMAP account
HABITS_SMTP_HOSTSMTP host (e.g. smtp.gmail.com)
HABITS_SMTP_PORTSMTP port (typically 587 for STARTTLS)
HABITS_SMTP_SUPPORT_USERGmail address for the support team inbox
HABITS_SMTP_SUPPORT_PASSWORDGmail App Password for the support inbox
HABITS_SMTP_SALES_USERGmail address for the sales team inbox
HABITS_SMTP_SALES_PASSWORDGmail App Password for the sales inbox
HABITS_SMTP_BILLING_USERGmail address for the billing team inbox
HABITS_SMTP_BILLING_PASSWORDGmail App Password for the billing inbox
HABITS_SMTP_FEEDBACK_USERGmail address for the feedback team inbox
HABITS_SMTP_FEEDBACK_PASSWORDGmail App Password for the feedback inbox
HABITS_SMTP_SPAM_USERGmail address for the spam/abuse inbox
HABITS_SMTP_SPAM_PASSWORDGmail App Password for the spam inbox
HABITS_SMTP_URGENT_USERGmail address for the urgent/critical inbox
HABITS_SMTP_URGENT_PASSWORDGmail App Password for the urgent inbox

How to set up ​

  1. Copy .env.example to .env and fill in your credentials.
  2. Enable 2-Step Verification on every Gmail account involved and generate a separate 16-character App Password for each (IMAP source + each team inbox).
  3. Run ticket-routing : it will fetch unread emails, classify them with AI, and forward each one to the appropriate team inbox automatically.

Tech stack ​

  • habits framework for workflow orchestration
  • OpenAI for natural-language ticket classification and priority scoring
  • IMAP (@ha-bits/bit-email) for Gmail inbox access
  • SMTP for forwarding routed tickets to team inboxes

Run Your .habit File ​

Run on Mobile

  • [ ] Download the Cortex App from store or the downloads page
  • [ ] Open the Cortex App on your device
  • [ ] Tap "Open Habit" or "+" button
  • [ ] Select your .habit file from your device storage
  • [ ] The habit will be loaded and ready to run

Run on Desktop

  • [ ] Download the Cortex App for your platform from the downloads page
  • [ ] Install and open the Cortex App
  • [ ] Click "Open Habit" or drag & drop your .habit file
  • [ ] The habit will be loaded and ready to run
  • [ ] Optional: Place a .env file in the same directory as your .habit file to override environment variables

Run on Server

Run your .habit file as a server using the Cortex CLI:

bash
# Install and run in one command
npx @ha-bits/cortex --config ./your-app.habit
  • [ ] Make sure Node.js 20+ is installed
  • [ ] Run the command above with your .habit file path
  • [ ] Server will start on the specified port (default: 3000)
  • [ ] Access the app at http://localhost:3000
  • [ ] Optional: Place a .env file next to your .habit file - it will automatically override any embedded environment variables

Run Serverless

For serverless or containerized deployments, we recommend using Docker:

bash
# Using Docker (recommended for serverless)
docker run -p 3000:3000 -v $(pwd)/your-app.habit:/app/habit.habit \
  node:20-alpine npx @ha-bits/cortex --config /app/habit.habit --host 0.0.0.0

Or create a Dockerfile:

dockerfile
FROM node:20-alpine
WORKDIR /app
COPY your-app.habit ./
COPY .env ./ # Optional: include environment variables
RUN npm install -g @ha-bits/cortex
EXPOSE 3000
CMD ["cortex", "--config", "./your-app.habit", "--host", "0.0.0.0"]
  • [ ] Create a Dockerfile or use the Docker run command above
  • [ ] Deploy to your preferred cloud provider (AWS, GCP, Azure, etc.)
  • [ ] Configure environment variables via your cloud provider's secrets management
  • [ ] Set up health checks at /habits/base/api endpoint

Workflow Visualization ​

Requirements ​

  • OPENAI_API_KEY (OpenAI API key)
  • GMAIL_IMAP_HOST (IMAP host for Gmail)
  • GMAIL_IMAP_PORT (IMAP port for Gmail)
  • GMAIL_IMAP_USER (Gmail address to read incoming tickets from)
  • GMAIL_IMAP_APP_PASSWORD (Gmail App Password for the IMAP account)
  • SMTP_HOST (SMTP host for Gmail)
  • SMTP_PORT (SMTP port for Gmail)
  • SMTP_SUPPORT_USER (Gmail address for the support team inbox)
  • SMTP_SUPPORT_PASSWORD (Gmail App Password for the support inbox)
  • SMTP_SALES_USER (Gmail address for the sales team inbox)
  • SMTP_SALES_PASSWORD (Gmail App Password for the sales inbox)
  • SMTP_BILLING_USER (Gmail address for the billing team inbox)
  • SMTP_BILLING_PASSWORD (Gmail App Password for the billing inbox)
  • SMTP_FEEDBACK_USER (Gmail address for the feedback team inbox)
  • SMTP_FEEDBACK_PASSWORD (Gmail App Password for the feedback inbox)
  • SMTP_SPAM_USER (Gmail address for the spam/abuse inbox)
  • SMTP_SPAM_PASSWORD (Gmail App Password for the spam inbox)
  • SMTP_URGENT_USER (Gmail address for the urgent/critical inbox)
  • SMTP_URGENT_PASSWORD (Gmail App Password for the urgent inbox)

Quick Start ​

Run using the Habits CLI wrapper, recommended if you develop local Habits

# First, download the example files
npx habits@latest cortex --config ./email-ticket-routing/stack.yaml
Download email-ticket-routing.habit

Get in touch

Want this habit running in your environment?

This habit is a starting point. Tell us about your stack and we'll help you get it working exactly the way your team needs.

Released under the AGPL-3.0 License.

Copyright © 2024-present Habits Team