EmailInsightAI

EmailInsightAI is not a mail client that replaces Gmail or Outlook. It is a monitoring layer over the mailboxes of a team. A company admin registers their employees' addresses once; from then on a background job reads new mail for every address, classifies it with Gemini, and stores the result. Admins and department heads then open the console and work from the classification rather than from the inbox.

The one thing to understand first

Almost every screen in the console is scoped to a mailbox owner, not to the person logged in. When you open a filter as an admin you are looking at your own mail; when you click through from the employee list, the same screen shows that employee's mail, and the employee's id travels in the URL (/mails/send-mail/42). If a screen looks empty, check whose mailbox you are in.

There is a single users table per company, and three fields decide what a row can do: user_level (what they may open), auth_id (which admin created them), and account_type (which mail provider to talk to).

Provider type

account_type decides which API is used for that mailbox, and it is chosen at registration:

• 0 — Google Workspace. A service account with domain-wide delegation impersonates the mailbox. The key lives at storage/app/email/service-account.json; reading uses the gmail.readonly scope and replying uses gmail.modify.
• 1 — Microsoft 365 / Outlook. An Azure AD app registration takes a client-credentials token for graph.microsoft.com/.default, cached in storage/app/email/outlook_account.json, and calls Microsoft Graph as the user.

Registration

1. Open /register and pick the account type — Google Workspace or Outlook.
2. Enter the mailbox address and a password (twice).
3. On submit, the app validates the address is unique, then tests the provider connection for that exact mailbox.
4. If the connection succeeds the account is created as a level-2 admin and you are returned to the form with a success message; if not, nothing is saved.

Signing in — password, then a one-time code

Login is two-step. The password is checked first but no session is opened yet; a six-digit code is generated, stored in user_otps with a five-minute expiry, and emailed. Only after the code verifies is the session created.

1. Enter email and password at /login.
2. Level-0 employees are stopped here by design.
3. A code arrives by mail, sent through Gmail SMTP as "EmailInsightAI — One Time Password for Secure Login".
4. Enter it on the OTP screen. Resend issues a fresh code and invalidates the old one.
5. The code is deleted on use and you land on the dashboard.

Forgotten passwords, and first password for a new head

• Forgot password. /forgot-password writes a 64-character token to password_reset_tokens and mails a link to /reset-password?token=…&email=….
• New department head. When an admin promotes someone to head, the app issues a reset token automatically and mails them a "You're Assigned as Department Head — Set Your Password" link pointing at /set-password. That link is how a head gets their first working password.

The dashboard

/dashboard is deliberately thin. It confirms which mailbox you are signed in as, shows a Google or Microsoft glyph for the provider, and re-tests the provider connection on every load. If that test fails you see "Please try Later" instead of the action buttons — that message means the provider connection is down or the credential file is missing, not that your password is wrong.

Email Inbox in the top navigation opens /mail-info. Two things happen on load: the page triggers a fetch for new mail for that mailbox, and it refreshes the toolbar counts from /mail/stats. The toolbar is the product — each chip is both a number and a link to the list behind it.

Each row in a list shows sender, subject, date, sentiment, label and action-required. On the reply-pending list the date column becomes Waiting for Reply Since, and the longer a message has waited the stronger the pill it gets — that is the intended way to triage a backlog.

Opening a message

View on any row opens /mails-show/{message}/{is_sent?}/{user?}. The stored HTML body is rendered with invisible-character cleanup applied (zero-width joiners, soft hyphens and similar are stripped so pasted content does not break layout). Attachments are flagged by the attachment_status column.

Replying from inside the console

Reply opens a compose form pre-filled from the original message. Sending goes out through the provider as the mailbox owner, in the original thread:

• Google. A fresh service-account token with the gmail.modify scope is minted for that mailbox, then a MIME reply is posted to the Gmail API carrying the original Message-ID and threadId so it threads correctly.
• Outlook. Microsoft Graph creates a reply draft on the original message and sends it, which keeps Graph's own threading intact.

How "Replied" is decided

Nothing marks a thread replied when you press send. The determination happens on the next ingestion run, and it is worth understanding because it explains why a reply can take a few minutes to show up in the counts.

The Summary chip is visible to admins. It takes the twenty most recent stored messages for the mailbox, excluding promotions and anything Gmail marked spam, joins each to its recorded response if one exists, and sends the batch to Gemini with instructions to return grouped HTML — newest thread first, with sender, recipient, date, subject, a one-line insight and a fuller summary covering actions, decisions, deadlines and attachments.

What you may see instead of a summary, and what it means:

A separate experimental page at /mic offers speech input, and public/dialogflow.php is a Dialogflow CX webhook that forwards a spoken question to Gemini and returns the answer. Neither is wired into the mail console — treat them as prototypes.

Bulk upload — the normal way to onboard

Add Email opens the bulk import screen. Download the sample workbook first; the importer checks the header row before reading anything else.

1. Click Download Sample and fill it in. Required columns, in order: First Name, Last Name, Email Id.
2. Upload the .xlsx. A mismatched header stops the import and tells you exactly which columns were expected.
3. Every row is tested against the mail provider before it is accepted.
4. Read the result table. Rows are sorted into four buckets and each bucket can be exported back to Excel:

The employee list

All Employee shows one row per monitored mailbox with its live counts: total, positive, negative, neutral, reply-pending, replied and promotion. Clicking a number opens /employee_process/{id}/{type} — the same list, scoped to that employee and that signal. A stored counter (freshcounts, keyed by admin) is polled in the background so the page can flag when new mail has landed for someone since you last looked.

Departments and heads

1. Settings ▸ Add Department — create departments with a name and a label. Names and labels must both be unique. Departments flagged non-deletable cannot be removed.
2. Settings ▸ Assign Department — pick a department, choose one head, tick the employees who report to them. The head is promoted to level 1 and emailed a set-password link; each employee gets Department_head_id and group_by set.
3. Settings ▸ Department Group — review heads per department and add more people under an existing head.
4. Remove on a member clears their head assignment. If that leaves the head with nobody, the head is demoted back to level 0 automatically.

Sender importance — Email Settings

Every new sender is added to a per-mailbox sender list automatically the first time they mail you. Email Settings splits that list into Important and Not Important, with per-sender counts of total, positive and negative messages. Tick the senders that matter and save: the ticked ones become important and every unticked sender is marked not-important in the same action. Selection is absolute, not additive.

Show all mail next to a sender lists every message stored from that address — the fastest way to audit one correspondent.

Inbox groups

Groups are saved sender sets that appear as extra entries under Group By.

1. Create a group under Inbox Groups.
2. From the sender list, assign senders to it.
3. The group shows up in the Group By dropdown as /mails/search-{group_id}, listing mail from all its senders.
4. Deleting a group releases its senders rather than deleting them.

Domain — internal versus outside

Domain stores one domain per user (default @gmail.com) and splits your sender list into matching and non-matching, with message counts on each side. Set it to your company domain to see at a glance how much traffic is internal and how much comes from outside.

Prompts and keywords

The prompt store lets an admin save a custom AI prompt (up to 200 characters) and a keyword label (up to 25). Saving a new one retires the previous active entry, so exactly one is live at a time. The active keyword is used as a heading for the positive-mail count in the console and in the daily report.

Every admin and every department head receives a Daily Summary mail listing the people they are responsible for. One row per mailbox, one column per signal, and every cell links straight into the matching filter in the console.

Because the queue is claimed per client and marked done, each client is mailed once per day even though the command runs many times inside the window. Sending is retried on the next tick if a client's job fails.

Ingestion and classification are one background command, app:process-email-queue, scheduled every ten minutes. It works through a queue of jobs — one job per mailbox per day — five at a time.

What Gemini is asked

The classifier prompt instructs the model to read only the new reply portion of a message — quoted history and "On … wrote:" blocks are explicitly excluded — and to answer with JSON only, always returning every field even when uncertain:

• action_required — send-mail if the message asks a question, requests help or needs a response; otherwise no-action.
• sentiment — positive, negative or neutral.
• category — amc for maintenance contracts, renewals, SLA and service visits; sales for pitches, quotations and leads that are not AMC; external for press, media and everything else.
• mass_mail — Outlook mailboxes also get promotion / transactional / other, because Graph has no equivalent of Gmail's Promotions label.

How the answer is stored

The raw JSON is kept in gemini_return_json and the words are kept in is_spam_value, is_action_required_value and is_category_value, so a classification can always be audited. Alongside them the answer is reduced to numeric codes that the filters query.

Promotion detection is label-driven for Gmail and model-driven for Outlook. Messages carrying Gmail's TRASH or DRAFT labels are neutralised so they cannot appear as inbound mail, and SENT messages are flagged as outbound rather than counted as received.

One Laravel application serves both halves of the system: an HTTP half that renders the console, and a console half that runs the scheduled ingestion and reporting. Both talk to the same providers, and both switch database connections at runtime depending on which company they are serving.

Multi-tenancy and the work queue

The master database is a registry, not a copy of anyone's mail. It holds the client list and two work queues. A seed script fills the queues once a day; the scheduled commands drain them, and for each job they repoint the clientdb connection at that client's schema before touching any data.

Request flows, end to end

Everything inside a client database hangs off users. There are no Eloquent relationships declared — joins are written explicitly — so the foreign keys below are the contract to respect.

Tables in a client database

Tables in the master database

Routes

Artisan commands

Environment

Credential files (not in version control)

• storage/app/email/service-account.json — Google service-account key with domain-wide delegation.
• storage/app/email/outlook_account.json — cached Graph access token; recreated automatically when it expires.

Log files

The app writes its own trace logs beside the Laravel log, in storage/logs/:

• MailController_check_load_time_log_cron.txt — stage-by-stage timings of a fetch run.
• MailController_log_cron.txt — ingestion errors and raw AI responses.
• MessageController_log.txt and MessageController_Gemini_response_log.txt — summary generation.
• MailController_flask_Api_log.txt — AI call failures and token usage.
• Job_fail_log.log — failed queue jobs.
• cron_seed_daily.log, cron_mail_seed.log — daily seeding.

Requirements

• PHP 8.2+ with curl, openssl, mbstring, zip (Excel) and imap if you use the legacy app-password path.
• MySQL 8 — one master database plus one database per client company.
• Composer dependencies; Node and Vite only if you rebuild front-end assets.
• A Google Workspace service account with domain-wide delegation, and/or an Azure AD app registration with application-level Mail permissions.
• A Gemini API key, and SMTP credentials for outbound mail.

Install

1. composer install --no-dev --optimize-autoloader
2. Copy .env.example to .env, then fill in both database blocks, GEMINI_API_KEY and the mail settings.
3. php artisan key:generate — do this once, before any mailbox secret is stored.
4. Load the schema. Because migrations are incomplete, restore from a known-good dump rather than running migrate on an empty database.
5. Drop the two credential JSON files into storage/app/email/.
6. Register the company in the master clients table with this installation's db_name and status = 'active' — without that row, nothing is ever queued.
7. Point the web root at public/ and make storage/ and bootstrap/cache/ writable.

Scheduling

Three cron entries drive everything. The seeds create the day's work; the Laravel scheduler drains it.

Capacity

Ingestion throughput is bounded by AI rate limits far more than by the database. If a backlog builds, raise the batch size and the per-mailbox cap together, and watch for 429 responses in MailController_flask_Api_log.txt.

These came out of reading the code for this document. None of them stop the product working; all of them are worth fixing before it carries more customers. Ordered by severity.