# Unified Inbox

The MailTrixy Unified Inbox consolidates all your email communication into a single, powerful interface. Connect multiple email accounts from different providers and manage every conversation from one place, eliminating the need to switch between tabs, clients, or services.

## Multi-Account Support

MailTrixy supports connecting multiple email accounts simultaneously. Each account appears as a separate mailbox in the sidebar, and you can view all accounts in a merged "All Inboxes" stream or filter by individual account.

### Supported Providers

- Gmail / Google Workspace: Connect via OAuth 2.0 with full read/write access. Supports labels, categories, and Gmail-specific features like importance markers.
- Microsoft Outlook / Office 365: Connect via Microsoft OAuth. Supports folders, categories, and focused inbox classification.
- IMAP/SMTP: Connect any standard IMAP-compatible email server. Configure incoming (IMAP) and outgoing (SMTP) servers separately with SSL/TLS support. Compatible with providers like Yahoo Mail, Zoho, FastMail, ProtonMail Bridge, and self-hosted mail servers.

> Tip: For optimal performance, OAuth connections (Gmail/Outlook) are recommended over IMAP. OAuth tokens refresh automatically and provide faster sync speeds.

## OAuth Connection Flow

Connecting a Gmail or Outlook account follows a secure OAuth 2.0 flow:

1. Navigate to Settings > Email Accounts > Add Account.
2. Select your provider (Gmail or Outlook).
3. You are redirected to the provider's consent screen where you grant MailTrixy read and send permissions.
4. Upon approval, MailTrixy receives an access token and refresh token. These are encrypted and stored securely in the database.
5. An initial sync begins immediately, pulling your recent emails (last 30 days by default). A background queue job handles the full historical sync.

Token refresh happens automatically before expiry. If a token becomes invalid (user revokes access), MailTrixy marks the account as "disconnected" and prompts re-authentication.

## Email Threading

MailTrixy groups related emails into conversation threads using the `In-Reply-To` and `References` headers, as well as subject-line matching. This keeps replies, forwards, and follow-ups organized under a single conversation view.

- Thread View: Click any email to see the full conversation thread in chronological order. Each message shows the sender, timestamp, and full body with inline attachments.
- Collapsed Messages: Long threads automatically collapse older messages, showing only the most recent 3 by default. Click "Show all messages" to expand.
- Thread Actions: Actions like archive, star, or label apply to the entire thread by default. Hold `Shift` to apply actions to individual messages within a thread.

## Starring, Pinning, and Archiving

Organize your inbox efficiently with quick-access actions:

- Star: Mark important emails with a star. Starred emails appear in a dedicated "Starred" filter view. Stars sync back to the provider (e.g., Gmail stars, Outlook flags).
- Pin: Pin critical conversations to the top of your inbox. Pinned threads always appear first regardless of date sorting. Pins are local to MailTrixy and do not sync to the provider.
- Archive: Remove emails from your inbox without deleting them. Archived emails are accessible through the "All Mail" view or via search. Archive status syncs to the provider.
- Trash: Move emails to trash. Trashed emails are permanently deleted after 30 days (configurable per workspace).

## Delivery Tracking

MailTrixy tracks the delivery status of every outgoing email, giving you visibility into whether your messages were successfully received:

- Sent: The email has been handed off to the outgoing mail server.
- Delivered: The recipient's mail server accepted the message. Confirmed via DSN (Delivery Status Notifications — automatic receipts from email servers confirming whether your message was delivered, bounced, or delayed) when available.
- Opened: The recipient opened the email. Tracked via a transparent 1x1 tracking pixel (a tiny invisible image embedded in the email that notifies you when the recipient opens it) (can be disabled per email or globally).
- Clicked: The recipient clicked a link in the email. Links are wrapped through MailTrixy's tracking redirect service.
- Bounced: The email could not be delivered. MailTrixy parses bounce messages to determine the bounce type:
  - Hard bounce: Permanent failure (invalid address, domain does not exist). The contact is automatically flagged.
  - Soft bounce: Temporary failure (mailbox full, server down). MailTrixy retries delivery up to 3 times over 24 hours.

Delivery status icons appear next to each sent message in the thread view, providing at-a-glance tracking without leaving the inbox.

## Scheduled Sending

Compose an email now and schedule it to be sent at a specific date and time. This is ideal for reaching recipients in different time zones or sending follow-ups at optimal times.

- How to Schedule: In the compose window, click the dropdown arrow next to the "Send" button and select "Schedule Send". Choose a date and time from the picker, or select a quick option (tomorrow morning, next Monday, etc.).
- Scheduled Queue: Scheduled emails appear in the "Scheduled" folder. You can edit or cancel any scheduled email before its send time.
- Time Zone: Scheduling respects the workspace's configured time zone. The send time displayed always reflects the workspace time zone setting.

## Auto-Reply Rules

Set keyword-based auto-replies that fire the moment an inbound message matches. Rules live at Settings → Auto-Reply Rules.

- Every channel: Rules work on Email, WhatsApp, SMS, Telegram, Slack, and Live Chat. Leave the channel filter as "All" or pin a rule to one channel.
- Match types:
  - Contains (default): the message body contains any of the keywords.
  - Exact phrase match: the trimmed, lower-cased message equals a keyword exactly (e.g. "hey").
  - Match all: the body contains every keyword in the list.
- Priority: Higher-priority rules are checked first. The first match wins; only one reply fires per inbound message.
- First message only (optional): when enabled, the rule only fires on the very first inbound message of a conversation.
- Reply body: HTML is supported for email. Non-email channels render the text content only.
- Synchronous delivery: replies are sent in the same request that received the incoming message, so customers see the response within a second — no queue-worker delay.
- Loop safety: replies from the auto-reply system itself (`sender_type = system`) and AI-generated drafts are never matched against rules, so no feedback loops.
- No rate limiting: every matching message fires a reply. If you want a throttle (e.g. one reply per hour), enable "First message only" on the rule.

## Email Snooze

Snooze an email to temporarily remove it from your inbox and have it reappear at a specified time. This helps you focus on what matters now without losing track of emails that need attention later.

- Quick Snooze Options: Later today (3 hours), Tomorrow morning (9 AM), Next week (Monday 9 AM), or custom date/time.
- Snooze Behavior: When snoozed, the email moves to a "Snoozed" folder. When the snooze time arrives, it reappears at the top of your inbox marked as unread, with a "Snoozed" badge.
- Cancel Snooze: Navigate to the Snoozed folder to view all snoozed emails and cancel any snooze early.

## Undo Send

MailTrixy provides a 10-second undo window after sending an email. During this window, the email is held in a local queue and not yet dispatched to the mail server.

- How It Works: After clicking "Send", a toast notification appears at the bottom of the screen with an "Undo" button and a countdown timer. Clicking "Undo" cancels the send and returns the email to the compose window with all content intact.
- Configurable Delay: The undo window duration can be adjusted in Settings > General > Undo Send Delay. Options are 5, 10, 20, or 30 seconds.
- Limitation: Undo send only works for emails sent through the MailTrixy compose interface. Emails triggered by automation workflows or API calls are sent immediately.

## Keyboard Shortcuts

MailTrixy supports a comprehensive set of keyboard shortcuts for power users. Press `?` at any time to open the shortcuts reference panel.

Shortcut | Action
--- | ---
`C` | Compose new email
`R` | Reply to current thread
`Shift + R` | Reply all
`F` | Forward current email
`E` | Archive selected thread
`S` | Toggle star on selected thread
`P` | Pin/unpin selected thread
`#` | Move to trash
`J / K` | Navigate down / up in email list
`Enter` | Open selected thread
`Escape` | Close thread / cancel compose
`Ctrl + Enter` | Send email
`Ctrl + Shift + E` | Schedule send
`Z` | Snooze selected email
`/` | Focus search bar
`?` | Show keyboard shortcuts panel

## Inbox Filters and Views

The inbox sidebar provides several built-in views and the ability to create custom filters:

- All Inboxes: A merged view of all connected accounts.
- Unread: Shows only unread conversations.
- Starred: All starred/flagged emails.
- Snoozed: Emails with an active snooze timer.
- Sent: Outgoing emails across all accounts.
- Drafts: Unsent draft emails.
- Scheduled: Emails waiting to be sent.
- Spam: Emails flagged as spam.
- Trash: Deleted emails pending permanent removal.
- Custom Filters: Create saved filters based on sender, recipient, subject, date range, has-attachment, labels, or any combination. Saved filters appear in the sidebar for one-click access.

## URL State & Reload Safety

The inbox keeps its state in the URL so you never lose your place on a page reload.

- `?c=<id>` — the currently-open conversation.
- `?channel=<name>` — the active channel filter (`email`, `whatsapp`, `sms`, `telegram`, `slack`, `chat`).
- `?folder=<name>` — the folder if not the default inbox (`sent`, `starred`, `snoozed`, `archive`, `trash`).

Refresh the page and the sidebar highlight, conversation list filter, and open conversation all come back exactly as they were. URLs are also copy-paste shareable — `/inbox?c=10296&channel=whatsapp` opens the same view for any teammate.

## Real-Time Background Refresh

A silent 5-second poll keeps the inbox live without any loading spinners. When a customer replies, your own outbound reply is sent, or a status update arrives:

- The sidebar unread counts update.
- The conversation list reorders.
- The currently-open thread pulls its latest messages and merges them into the view (de-duplicated, sorted chronologically by message id).

No spinner flash, no scroll jump, no page reload. If you're online, the inbox stays in sync.

## Full Thread Auto-Load

Opening a conversation fetches the entire thread in one request (up to 500 messages). For threads longer than 500, remaining pages auto-load in the background — no manual "Load more" clicks until the 10,000 message safety cap.

Messages always display in chronological order: oldest at the top, newest at the bottom. This holds across every channel (Email, WhatsApp, SMS, Telegram, Slack, Live Chat).

## Internal Notes

Click the Note tab in the reply composer to leave a team-only comment on a conversation. Notes:

- Render inline in the thread as a yellow "Internal Note" card with the author's name and timestamp.
- Are never delivered to the customer — no email, no WhatsApp, no Slack.
- Appear instantly when added (no page reload) and persist across reloads.
- Are searchable alongside regular messages.

## Quick Replies & Slash Shortcuts

Click Quick Replies in the left sidebar to manage saved reply templates without leaving the inbox — the panel slides in over the conversation pane, same pattern as Compose.

Inside any conversation, type `/` followed by a shortcut (e.g. `/hi`, `/hours`) in the Compose editor or the Reply editor. A dropdown appears with matching canned responses — click one to insert it. The match looks at the canned response's title, shortcut, and content.

## Compose Channel Defaulting

When you click Compose, the channel tab in the composer automatically matches whichever channel you're currently browsing:

- In the WhatsApp filter? Compose opens on the WhatsApp tab.
- In the SMS filter? Compose opens on the SMS tab.
- Same for Telegram, Slack, and Email.
- "All" or "Live Chat" fall back to the Email tab (since Live Chat is visitor-initiated).

## Sidebar Layout

The left sidebar groups related items with dividers so navigation stays clean:

- Folders (Inbox, Sent, Starred, Snoozed) — highlighted only when `channel=all`. Picking a channel filter dims the folder pill so there's only ever one "active" highlight.
- Agent-reachable channels (Email, WhatsApp, SMS, Telegram, Slack) — two-way messaging.
- Live Chat — in its own group with a divider because it's visitor-initiated from a website widget, not an outbound-reachable channel.
- Bottom group (Archive, Bin, Quick Replies, Settings, Exit Inbox).