All jobs

Track Candidate Replies in Each Recruiter's Gmail From Your Recruiting Software

Recruiting software makes one agent per recruiter with read-only Gmail; it reads candidates' replies and returns a suggested next step for each to approve.

Run this on RushOpens the console with this prompt ready to send. Connect Gmail there first.

What the agent does

This is for a company that sells software to recruiting agencies and in-house talent teams. Its recruiters email candidates from their own Gmail, and the replies ("yes, Tuesday works", "I accepted another offer", "what's the salary range?") sit in each inbox until someone copies them into the pipeline. The company saves one agent as a template with Gmail at the read level: "connections": [{"name": "gmail", "access": "read"}]. Each recruiter's Google consent page then asks for gmail.readonly alone, and every run of their agent refreshes the token for that scope alone, so the agent can read mail and cannot send, delete or label it.

When a recruiter turns the feature on, the backend makes their agent from the template ({"template": "<template id>", "name": "replies-<recruiter id>"}), then calls POST /o/{org}/agents/{agent}/connections {"type": "app", "name": "gmail"} and opens the returned authorize_url in a popup for that recruiter. The recruiting company registers no Google app and stores no token. It stores the agent id against the recruiter.

Each run's input is the list the recruiting software already has: the candidates this recruiter is waiting on, each with their email address, the role and the stage. The agent calls the Gmail REST API's users.messages.list with a q in Gmail's search syntax, such as from: each candidate's address and after: the last check, then reads each message and its thread with users.messages.get. It reads only those candidates' mail; the prompt says so, and the search keeps the rest of the inbox out of the run.

For each reply it decides what the candidate said: interested, declined, proposed times, asked a question, or sent a document. It pulls out the concrete parts (the times offered with their timezone, the question asked, the attachment's file name) and suggests the next pipeline step. It does not decide anything about the candidate's fit, and it suggests a move only when the words of the reply support it.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "<agent id>",
  "input": "Check replies since 2026-11-11 09:00 UTC from these candidates: ana.ruiz@example.com (Senior Accountant, stage: phone screen invited), j.okafor@example.com (Payroll Specialist, stage: offer sent), lee.marsh@example.com (Controller, stage: first contact). Search Gmail only for mail from these addresses after that time, and read each matching message and its thread. For each candidate return: replied (true/false), intent (interested, declined, proposed_times, question, document, other), a one-sentence summary in your own words, proposed times with timezone if any, the question if any, attachment names if any, and suggested_stage only when the reply clearly supports it. Return only JSON. Do not judge the candidate's suitability."
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The answer is a JSON list, one entry per candidate, in the session's result and in the run.completed webhook's data.result (in full up to 16 KiB; a longer one is read from session_url). The recruiting software matches each entry to the candidate by email address and shows the suggestion beside the pipeline card: "Proposed Tue 10:00 or Wed 14:00 ET, move to phone screen scheduled?" The recruiter accepts or edits it with one click, so nothing in the pipeline moves on the agent's word alone.

Before trusting a suggestion, the recruiter reads the summary against the reply, which is a click away in their own Gmail. A reply that mixes intents, such as a decline that asks to be kept in mind for later, is marked other with the summary carrying the detail. The session records which mailbox it read in accounts, and GET /o/{org}/sessions?account=<recruiter email> lists every run that touched that mailbox.

Run it on every few hours, per recruiter

The recruiting software's scheduler sends one POST /o/{org}/sessions per recruiter with open conversations, every few hours during their working day, with the candidate list and the time of the last check in input. A request_id that is a UUID v5 of the recruiter's id and the window start keeps a retried job from starting a second run. Recruiters with nobody waiting get no run.

A webhook on the API key receives each run.completed; the handler verifies the Standard Webhooks signature, looks up the recruiter by execution_id, and writes the suggestions. When a recruiter's run is refused or fails with a message that asks to reconnect Gmail, the software shows them a reconnect button instead of stale suggestions.

The use case this job follows, with its automation and trigger: Run an agent per customer task.

Why run it on Rush?

Reading other people's mail on their behalf is the part of this feature that needs the most care. On Rush each recruiter's Gmail belongs to their own agent: one agent's run never sees another's inbox or the company's own accounts, the read level keeps the grant to reading, and Rush refreshes the token outside the sandbox so it never enters the agent's computer.

Every run is recorded: the searches the agent made, the messages it opened, and the suggestions it returned, so when a recruiter asks why the software moved a candidate, there is an answer. A session that used a connected Gmail is readable only by whoever started it and the org's owners and admins. Recruiters' runs go in parallel, each in its own computer, up to the key's concurrent run limit, with the rest queued.

Frequently asked questions

Can the agent reply to candidates?

Not with this template. The read level asks Google for gmail.readonly only, so the token cannot send. A product that wants drafted replies would use the send level, which recruiters would grant again on Google's consent page.

Does the agent read the rest of the recruiter's inbox?

The run searches only for mail from the candidates in its input and the prompt tells it to read nothing else. The grant itself covers the whole mailbox, as any read-only Gmail grant does, which is why the transcript of every run is kept for review.

What if a recruiter uses two Gmail accounts?

An agent holds one account per app, and connecting another replaces it. Make one agent per mailbox from the same template, and keep both ids against the recruiter.

What happens when a recruiter leaves the agency?

Call DELETE /o/{org}/agents/{agent}. It disconnects that agent's Gmail, revoking Rush's access at Google unless another of your live agents holds the same Google account, and the agent starts no new runs.

More Gmail jobs

More jobs like this: Run an agent per customer task

Keep reading