pyr0ball
8cb636dabe
Adds a full MkDocs documentation site under docs/ with Material theme. Getting Started: installation walkthrough, 7-step first-run wizard guide, Docker Compose profile reference with GPU memory guidance and preflight.py description. User Guide: job discovery (search profiles, custom boards, enrichment), job review (sorting, match scores, batch actions), apply workspace (cover letter gen, PDF export, mark applied), interviews (kanban stages, company research auto-trigger, survey assistant), email sync (IMAP, Gmail App Password, classification labels, stage auto-updates), integrations (all 13 drivers with tier requirements), settings (every tab documented). Developer Guide: contributing (dev env setup, code style, branch naming, PR checklist), architecture (ASCII layer diagram, design decisions), adding scrapers (full scrape() interface, registration, search profile config, test patterns), adding integrations (IntegrationBase full interface, auto- discovery, tier gating, test patterns), testing (patterns, fixtures, what not to test). Reference: tier system (full FEATURES table, can_use/tier_label API, dev override, adding gates), LLM router (backend types, complete() signature, fallback chains, vision routing, __auto__ resolution, adding backends), config files (every file with field-level docs and gitignore status). Also adds CONTRIBUTING.md at repo root pointing to the docs site.
119 lines
3.9 KiB
Markdown
119 lines
3.9 KiB
Markdown
# Email Sync
|
|
|
|
Peregrine monitors your inbox for job-related emails and automatically updates job stages when it detects interview requests, rejections, offers, and survey links.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Email sync is configured in `config/email.yaml` (gitignored). Copy the example template to get started:
|
|
|
|
```bash
|
|
cp config/email.yaml.example config/email.yaml
|
|
```
|
|
|
|
Then fill in your credentials:
|
|
|
|
```yaml
|
|
host: imap.gmail.com
|
|
port: 993
|
|
use_ssl: true
|
|
username: your.email@gmail.com
|
|
password: xxxx-xxxx-xxxx-xxxx # see Gmail App Password below
|
|
sent_folder: "" # leave blank to auto-detect
|
|
lookback_days: 90 # how many days back to scan
|
|
todo_label: "" # optional Gmail label to monitor
|
|
```
|
|
|
|
You can also configure email sync via **Settings → Email** in the UI.
|
|
|
|
---
|
|
|
|
## Gmail Setup
|
|
|
|
Gmail requires an **App Password** instead of your regular account password. Your regular password will not work.
|
|
|
|
1. Enable **2-Step Verification** on your Google Account at [myaccount.google.com/security](https://myaccount.google.com/security)
|
|
2. Go to [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords)
|
|
3. Create a new app password — name it "Peregrine" or similar
|
|
4. Copy the 16-character code (no spaces) and paste it as `password` in `config/email.yaml`
|
|
5. Enable IMAP in Gmail: **Settings → See all settings → Forwarding and POP/IMAP → Enable IMAP**
|
|
|
|
---
|
|
|
|
## Outlook / Office 365
|
|
|
|
```yaml
|
|
host: outlook.office365.com
|
|
port: 993
|
|
use_ssl: true
|
|
username: your.email@company.com
|
|
password: your-password # or App Password if MFA is enabled
|
|
```
|
|
|
|
---
|
|
|
|
## Gmail Label Monitoring (Optional)
|
|
|
|
If you use a Gmail label to flag action-needed job emails (e.g. "TO DO JOBS"), set:
|
|
|
|
```yaml
|
|
todo_label: "TO DO JOBS"
|
|
```
|
|
|
|
Emails in this label are matched to pipeline jobs by company name, then filtered by action keywords in the subject line (e.g. "interview", "next steps", "offer").
|
|
|
|
---
|
|
|
|
## Email Classification Labels
|
|
|
|
The email classifier assigns one of six labels to each relevant email:
|
|
|
|
| Label | Meaning |
|
|
|-------|---------|
|
|
| `interview_request` | Recruiter or hiring manager requesting a call or interview |
|
|
| `rejection` | Automated or personal rejection |
|
|
| `offer` | Job offer letter or verbal offer notification |
|
|
| `follow_up` | Candidate or recruiter follow-up with no stage change |
|
|
| `survey_received` | Link or request to complete a culture-fit or skills assessment |
|
|
| `other` | Job-related but does not fit any category above |
|
|
|
|
Classification is performed by your configured LLM backend. The classifier uses the email subject and body as input.
|
|
|
|
!!! note "Tier requirement"
|
|
Email classification is a Paid feature.
|
|
|
|
---
|
|
|
|
## Stage Auto-Updates
|
|
|
|
When a classified email is matched to a job in your pipeline, Peregrine updates the job stage automatically:
|
|
|
|
| Classification | Stage action |
|
|
|---------------|-------------|
|
|
| `interview_request` | Moves `applied` → `phone_screen` |
|
|
| `rejection` | Moves job → `rejected` (captures `rejection_stage`) |
|
|
| `offer` | Flags job for review; moves toward `offer` stage |
|
|
| `survey_received` | Moves job → `survey` pre-stage |
|
|
|
|
Emails are matched to jobs by comparing the sender domain and company name in the email body against company names in your pipeline.
|
|
|
|
---
|
|
|
|
## Running Email Sync
|
|
|
|
### From the UI
|
|
|
|
Click **Sync Emails** on the Home page. This runs as a background task — you can navigate away while it processes.
|
|
|
|
### Non-blocking background sync
|
|
|
|
Email sync runs in a daemon thread via `scripts/task_runner.py` and does not block the UI. The sidebar background task indicator shows sync progress.
|
|
|
|
---
|
|
|
|
## Email Thread Log
|
|
|
|
All matched emails are stored in the `job_contacts` table (one row per email thread per job). You can view the thread log for any job from the Job Review detail view or the Interviews kanban card.
|
|
|
|
Columns stored: `direction` (inbound/outbound), `subject`, `from`, `to`, `body`, `received_at`.
|