Documentation Index
Fetch the complete documentation index at: https://docs.xysq.ai/llms.txt
Use this file to discover all available pages before exploring further.
The Gmail integration lets xysq receive new mail from your inbox and your sent folder, run it through a filter you control, and store what’s worth remembering. Once connected, every reply you send, every meaningful email you receive, every confirmation and receipt — they all become recallable memories without you copy-pasting anything.
Connect Gmail
- Click Connect Gmail on the Gmail card.
- A new tab opens for Google’s OAuth consent screen. Sign in and approve the requested scopes (read-only access to your messages and metadata).
- The new tab closes itself after consent. The Integrations card flips from “Pending” to “Connected” within a few seconds.
xysq watches both your inbox and your sent folder, so:
- Inbound mail you receive → ingested if it passes your rules.
- Replies you send → ingested under the same conversation thread.
- Cold outreach you send first → ingested even if no reply ever comes back.
There’s a per-user daily cap of 50 events/day by default. It stops a noisy inbox from saturating your memory. The card shows a progress bar so you can see how close you are to the cap. If you hit it, syncing pauses until midnight UTC.
What gets kept by default
xysq ships an opinionated default rule set. Out of the box:
| Default | Effect |
|---|
| Skip Gmail’s Promotions category | Filtered before reaching your memory |
| Skip Gmail’s Social category | Same |
| Skip Spam | Same |
Skip messages with a List-Unsubscribe header | Catches mailing-list traffic |
Skip messages from *.mailchimp.com | Common newsletter domain |
Skip messages from no-reply@* senders | Transactional noise |
Keep direct replies (any message with In-Reply-To) | Personal conversations |
| Keep flight confirmations (LLM-gated) | Verified by lite LLM before ingesting |
| Keep receipts/invoices (LLM-gated) | Same |
| Anything else | Kept by default |
Manage filter rules
Click Manage rules on the Gmail card to open the rule editor at /connect-apps/gmail/filters.
The editor is a YAML pane (Monaco) on the left and a live view of your effective rule set on the right. The defaults above are pre-populated as real, editable YAML — you can tweak any of them or add your own.
Rule schema
Every rule has:
id — your name for it. Same id as a default rule overrides that default. New ids append.action — keep or skip.priority — higher number wins when two rules match the same message. Defaults sit in the 40–100 range; user rules typically go 100–200 for stronger override.when — a list of conditions that all must match.llm_hint (optional) — when present, the lite LLM is asked to confirm or reject the match using this hint. Useful for ambiguous categories like “flight confirmation” where keyword matching is too crude.tags (optional) — extra tags to attach to the resulting memory (e.g. gmail:transactional, domain:travel).
Condition fields
The when list supports these fields and operators:
field | What it inspects |
|---|
subject | The subject line |
sender | The full From: header (display name + email) |
sender_domain | Just the domain part of the sender’s email |
body | The plain-text message body |
label_ids | Gmail labels on the message (INBOX, IMPORTANT, CATEGORY_*) |
in_reply_to | The In-Reply-To header — used to detect direct replies |
header:<Name> | Any other RFC822 header by name |
op | What it does |
|---|
equals | Exact match |
contains_any | value is a list — true if any item is a substring |
matches | fnmatch-style glob (*.mailchimp.com) |
regex | Full regex match against the field |
exists | True if the field is non-empty |
in_list | value is a list — true if the field is one of them |
Example: “always keep messages from my boss”
rules:
- id: keep-from-my-boss
action: keep
priority: 200
when:
- field: sender
op: contains_any
value:
- boss@example.com
tags:
- gmail:work
Validation
The editor validates as you type. Errors appear inline with line numbers. The Save button stays disabled until validation passes — you can’t accidentally save a broken config. The right rail re-renders with your new effective rule set after every save.
Activity logs
Open app.xysq.ai/logs (or click View logs on the Gmail card to pre-filter to Gmail) to see every event xysq has processed.
Each row shows:
- Time — when xysq received the event.
- App — which integration produced it (Gmail today; more later).
- Decision — Kept, Skipped, or Paused (cap reached or service paused).
- Subject + Sender — snapshot of the message metadata.
- Why — human-readable explanation. Examples:
- “Matched rule: keep-personal-replies”
- “LLM verdict (under rule keep-flights-llm): real flight confirmation”
- “Default skip — Gmail category Promotions”
- “Kept by default (no skip rule matched)”
- “Folded into existing thread”
Keep anyway
Every Skipped or Quota-dropped row has a Keep anyway action button. Click it to override the original decision and pull that message into your memory after the fact — useful when you spot a real email that the filter mis-classified.
What happens behind the scenes:
- xysq fetches the full message from Gmail.
- Runs it through the keep pipeline (same as a live event).
- Updates the audit row in place — the original timestamp stays, the decision flips to Kept, and the row’s reason is marked as a manual override.
The message becomes recallable in chat and visible in the Vault tagged source:gmail.
Disconnect Gmail
Click Disconnect on the Gmail card. A confirmation dialog appears explaining what stays and what stops.
| Stays | Stops |
|---|
| Every email already in your vault | New emails arriving in xysq |
| All your custom filter rules | xysq’s watch on your Gmail account |
| Your full activity-log history | Your OAuth grant (Google revokes our access) |
- Same connection record → same daily cap, same configuration.
- Same filter rules → no need to re-edit.
- Same logs → full history visible from day one.
- Past messages already in your memory never get re-ingested, even if Gmail re-delivers them on the first sync after reconnect.
The only thing you lose by disconnecting is the window between disconnect and reconnect — incoming mail during that gap won’t sync (it’ll still arrive in your Gmail inbox normally; xysq just won’t see it).