# Gmail filter tool

The authenticated `/tools/add-filter` page works on newtopc.com and runwaydo.com. Every endpoint requires HTTPS and a user whose saved domain equals the current request host. The server selects accounts through `accounts.project_id → projects.domain`; the browser cannot select another website's accounts. Revoked and denied accounts are excluded. Ownership and availability are checked again when jobs run and before each filter operation.

Choose a subject phrase or enter up to 50 sender domains (one per line; commas, semicolons and whitespace also work). Domains are validated, converted to ASCII, and deduplicated. Each domain becomes a separate Gmail `criteria.from` rule with `@example.com`. These use Gmail's sender matching semantics. Subject rules use Gmail's case-insensitive phrase matching. Actions match the desktop script: remove INBOX, UNREAD, SPAM; add STARRED and IMPORTANT. Creation applies to future incoming messages; existing messages are not modified.

The tool reuses legacy OAuth credentials and encrypted Inbox connections. It verifies Google mailbox identity before changing filters. Linked connections must include `gmail.settings.basic`. Existing criteria and actions are compared, ignoring label order and empty criteria. Identical rules are reported as already existing; matching criteria with other actions are reported as failures for manual review. No existing filters are deleted or changed.

## Runtime

The Start account and End account inputs are inclusive, one-based positions among this website's active accounts, sorted by ascending database ID. They default to the whole list. With 3,529 active accounts, 3521–3529 selects exactly the last nine. Revoked accounts, other websites' accounts and gaps in real IDs do not occupy positions. The server validates the range against the current list, freezes the selected IDs before batching, and saves each selected position. Retries retain that selection; they do not reselect accounts from a changing list. The saved range appears in progress and history, and results and exports follow ascending ID order.

Also apply `database/migrations/2026_11_10_000002_add_account_ranges_to_gmail_filter_runs.php` for range metadata and account positions. Existing run records remain readable.

Apply `database/migrations/2026_11_10_000001_create_gmail_filter_runs.php`. It adds `gmail_filter_runs` and `gmail_filter_accounts`. Snapshots and dedicated database queue jobs commit together on the application's default database; this does not use `DB_QUEUE_CONNECTION` or `DB_QUEUE_TABLE`. Runs are constrained to one active run per website, and repeat submissions with the same request UUID return the same run.

Three systemd workers consume only the `gmail-filters` queue through the `gmail_filters` connection:

```bash
cp docs/gmail-filter-worker@.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now gmail-filter-worker@1 gmail-filter-worker@2 gmail-filter-worker@3
```

After code updates, restart these specific services to reload the worker code. They automatically restart after failure and recycle hourly. Queue reservation expiry (90 seconds) exceeds job timeout (70 seconds), HTTP requests time out after 8 seconds, and each account saves progress and yields after approximately 45 seconds. Cache locks prevent duplicate jobs or concurrent alias connections from processing the same mailbox. Cache locks must use the application's shared cache in multi-server deployments.

The queue listener saves a throttled heartbeat used by the progress page. Three workers provide bounded concurrency; users do not configure threads. Google rate limits and transient failures get up to three automatic retries per account. An ambiguous create response always triggers a fresh filter listing before retrying. Successfully checkpointed results survive retries and worker restarts. Repeated worker timeouts become visible failures. Manual retry requeues only failed accounts and preserves successful rule results.

The page polls every two seconds, reconnects after network failures, and restores progress using `?run=<uuid>`. Results are paginated, with a failed-only view, a full CSV report, and a TXT export containing accounts for which all rules succeeded or already existed. CSV formula-leading cells are escaped. Runs and results are available only on their original website. Records contain account identifiers, criteria and sanitized results; OAuth tokens and raw Google error bodies are never returned in progress, exports or job payloads.

## Verification

```bash
php artisan test --compact tests/Feature/Inbox/GmailFilterToolTest.php
node --check public/js/gmail-filters.js
```

The feature tests use in-memory SQLite and fake Google HTTP responses, including a real database queue job. They do not change real Gmail accounts.
