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:

cp config/email.yaml.example config/email.yaml

Then fill in your credentials:

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.

Enable 2-Step Verification on your Google Account at myaccount.google.com/security
Go to myaccount.google.com/apppasswords
Create a new app password — name it "Peregrine" or similar
Copy the 16-character code (no spaces) and paste it as password in config/email.yaml
Enable IMAP in Gmail: Settings → See all settings → Forwarding and POP/IMAP → Enable IMAP

Outlook / Office 365¶

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:

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.

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.