recruit
read-only · imap

Sign it in.
It only reads.

Recruit connects to one INBOX over IMAP. Every provider below needs the same two things from you: an app-specific password, and the right server, port and TLS setting.

one INBOX 90 days no OAuth no sending

passwords → macOS Keychain
messages → local SQLite
neither leaves the machine

$ connect imap.gmail.com:993 tls
* OK Gmail ready.
 
a1 LOGIN you@gmail.com ••••••••••••••••
a1 OK LOGIN completed
a2 SELECT INBOX
* 2841 EXISTS
a3 SEARCH SINCE 28-May-2026
* SEARCH 2751 2752 2753 …
a4 FETCH 2751:* (BODY.PEEK[])
↑ PEEK — does not set \Seen
 
# no code path sends these:
a5 STORE 2751 +FLAGS (\Seen)
a6 EXPUNGE
a7 APPEND "Sent" {…}
How it connects

What it does with the account

Worth knowing before you hand it a password. Recruit signs in as a mail client, pulls the last 90 days of your INBOX, and never sends a command back that changes anything on the server.

STORE · EXPUNGE · APPEND Provider IMAP imap.example.com:993 Recruit sync + prefilter INBOX · 90 days recruit.db messages + scores macOS Keychain app password messages store password
The password takes one path — into the Keychain — and only SQLite ever grows. The dashed edge is the one Recruit never opens: v1 has no code that writes an IMAP flag, moves a message or sends mail.

What you do in the app

  1. 01
    Settings → Account you

    Choose your provider from Provider. The servers, ports and TLS toggles fill themselves in.

  2. 02
    Email address autofills

    Typing it copies the address into both Username fields. Override them only if your provider says otherwise — iCloud sometimes does.

  3. 03
    Password you

    The app-specific password from the section for your provider below. Not your account password.

  4. 04
    Test IMAP connection server

    A real sign-in, before anything is saved. Wait for the green result — a saved account with a bad password just fails later, at sync.

  5. 05
    Save, then Sync recruit

    Messages scoring 0.5 or higher in the prefilter become candidates for the agent to triage.

Optional

SMTP does nothing in this version. Recruit stores and connection-tests the outgoing half so sending can land later, but nothing sends today. Leave it blank and everything still works.

Ports & TLS

One switch causes most first-run failures

Use TLS means this port is encrypted from the first byte. It is not a "should this be secure?" question. Turn it off on 143 and 587 and the connection still gets encrypted — by STARTTLS, a step later.

INCOMING · IMAP 993 Use TLS · on 143 off → STARTTLS OUTGOING · SMTP 465 Use TLS · on 587 off → STARTTLS
Match the toggle to the port, not to your instincts about security. Mismatch it and the test fails during the handshake, not at authentication — which is why Recruit reports those two failures with different words.
Provider

Gmail

works

IMAP has been on by default for every Google account since January 2025 — there is no setting to enable. What you need is an app password, and app passwords only exist once 2-Step Verification is on.

  1. 01
    Turn on 2-Step Verification you

    At myaccount.google.com/security, if it isn't already. Without it the app-passwords page does not exist.

  2. 02
    Create the app password you

    Go to myaccount.google.com/apppasswords, name it Recruit, and create it.

  3. 03
    Paste it without the spaces you

    Google prints it in four groups for readability and the groups are not part of it: abcd efgh ijkl mnop goes in as abcdefghijklmnop. Sixteen characters. The same password works for IMAP and SMTP.

RoleServerPortUse TLSUsername
IMAPimap.gmail.com993onfull address
SMTPsmtp.gmail.com465onfull address
No app-passwords page?

Three causes, in order of likelihood: 2-Step Verification is off; the account is enrolled in Advanced Protection, which removes app passwords entirely; or it is a Workspace account whose admin has disabled them. Only the first is yours to fix.

Scope

Recruit only reads INBOX. A Gmail filter that archives or labels recruiter mail on arrival takes it out of INBOX, and Recruit will never see it. Promotions and Updates are still INBOX, so those do get picked up.

Provider

iCloud Mail

works username quirk

Apple requires two-factor authentication on the Apple Account before it will issue an app-specific password. The quirk is the username: Apple documents the name part of your address for incoming mail, and the full address for outgoing.

  1. 01
    Generate the password you

    Sign in at account.apple.com → Sign-In and Security → App-Specific Passwords. Label it Recruit and copy it. Apple shows it once.

  2. 02
    Pick the iCloud preset, paste, test server

    If it authenticates, you're done. If it doesn't, the username is the thing to change — see below.

IMAP username you@icloud.com test signs in? yes Done — save it no retry with the prefix you
The password is unchanged between the two attempts — only the username field moves. If the prefix works, leave Email address as the full address; it is a separate field from Username.
RoleServerPortUse TLSUsername
IMAPimap.mail.me.com993onfull address, else prefix
SMTPsmtp.mail.me.com587offfull address
Aliases

@me.com and @mac.com aliases use the same servers and the same app-specific password — sign in with whichever address the mailbox actually answers to.

Provider

Fastmail

works

Fastmail refuses your normal password on IMAP outright, so an app password is not a 2FA workaround here — it is the only way in. The one thing to get right is the scope.

  1. 01
    Settings → Privacy & Security → Connected apps you

    Then New app password.

  2. 02
    Give it a scope that includes Mail you

    Either scope that includes Mail is fine. A Contacts- or Calendars-only token authenticates against CardDAV and CalDAV and is rejected on port 993.

RoleServerPortUse TLSUsername
IMAPimap.fastmail.com993onfull address
SMTPsmtp.fastmail.com465onfull address
Aliases

Using a Fastmail alias or your own domain? Sign in with the account's primary address, not the alias — the alias delivers to the same mailbox but is not a login.

Provider

Outlook & Microsoft 365

no way in

Recruit ships an Outlook preset and it will not authenticate. Microsoft has removed password-based sign-in from IMAP and SMTP: personal Outlook.com accounts lost it on 16 September 2024, Exchange Online mailboxes earlier, and the last SMTP holdout closed on 30 April 2026. The only remaining door is OAuth, which Recruit has no client for.

Recruit app password basic auth — refused OAuth client not built the path Microsoft accepts Exchange Online outlook.office365.com
Nothing you can set in Recruit or in your Microsoft account bridges the gap — app passwords for Microsoft accounts were themselves a basic-auth mechanism, and went with it.
The way around it

If your job mail lives in Outlook, the practical route today is a forwarding rule from Outlook into a mailbox Recruit can read, and pointing Recruit at that one instead. Set the rule up in Outlook yourself — Recruit cannot create it.

Provider

Anything else

custom…

Pick Custom… and fill the four IMAP fields by hand. Providers publish these under "IMAP settings" or "mail client setup"; the pattern is nearly always the same.

Server

imap.yourdomain.com

Usually that, or mail.yourdomain.com. Your webmail's hostname is not always the IMAP one.

Port & TLS

993 with TLS on

Unless the provider says 143 — in which case turn Use TLS off and let STARTTLS do it.

Username

The full address, usually

Some shared hosting uses a cPanel-style user@domain that differs from your display address.

Password

An app password, if offered

If the account has 2FA and the provider has no app-password feature, IMAP will not work at all.

No plain IMAP endpoint

Proton and Tutanota encrypt mailboxes in a way that has no plain IMAP endpoint. Proton exposes IMAP only through Proton Mail Bridge running locally, so Recruit would point at 127.0.0.1 with the Bridge's own generated password. Tutanota has no IMAP at all.

When it fails

Read the message before changing anything

Recruit distinguishes the failure modes deliberately, so the message tells you which layer broke.

Authentication failed — check the username and password.
You reached the server and it said no. Almost always a normal password where an app password belongs, or spaces left in a pasted one. Also check the app password wasn't revoked — changing your main account password kills every app password with it.
The connection failed during the handshake — the TLS setting probably does not match the port.
The credentials were never tried. Use TLS disagrees with the port: on for 993 and 465, off for 143 and 587.
Host not found: imap.example.com
A typo in the server name, or you're offline. Compare against the table in your provider's section.
Timed out connecting — wrong port, or a firewall is in the way.
Corporate networks and some VPNs block 993 outright. Try the same account off the network to tell the two apart.
Connection refused — nothing is listening on that port.
Right host, wrong port. Check for a transposed 993/143.
TLS certificate rejected for imap.example.com
The certificate doesn't match the hostname or has expired. On a self-hosted server that's a real misconfiguration; on a public provider, suspect a network appliance intercepting the connection.
Not an auth problem

Connection fine, but no mail appears? Recruit syncs INBOX only, and only the last 90 days — mail that a server-side filter moved to a folder or label never appears.