Skip to main content
Some ATS flows pause an application on an email verification step: the provider emails a one-time code to the candidate’s address and the application’s current_step carries a field with format: "one_time_code" that expires in 90 seconds. Others email a confirmation link that has to be clicked before the application counts as submitted.
Connecting a mailbox is entirely optional. Verification steps work the same whether or not Jobo can see the inbox — the code is just another answer on the step, so if you already read that mailbox yourself, keep doing exactly that and submit the code through POST /applications/{id}/answers as usual. These endpoints exist purely so you don’t have to build and operate IMAP/OAuth inbox access if you’d rather not. Nothing else in Auto Apply depends on them, and you can adopt them for some mailboxes and not others.
With a mailbox connected, Jobo retrieves a code or visits a confirmation link. For a code, you then submit it as an answer:
Connect only a mailbox whose owner has authorized this access. Use the same account for the mailbox and its applications.

​
Connect a mailbox once

Mailboxes are account-level resources — connect each inbox once and reference its id from any application. Two providers:
  • imap — host, address, and a password (use an app password where the provider offers them, e.g. Gmail). Credentials are verified synchronously on create: you either get status: "connected" back or a mailbox_verification_failed problem and nothing is stored.
  • outlook — this provider uses a hosted Microsoft consent flow and reads over Microsoft Graph (delegated Mail.Read). Create returns status: "pending" plus an authorization_url; open it (or send it to the mailbox owner), sign in with the same address you declared, and the mailbox flips to connected. The consent link expires after 15 minutes — fetch the mailbox again for a fresh one. No IMAP host is needed or returned for this provider.
Secrets are encrypted at rest with the same envelope scheme as application data and are never returned by any endpoint. DELETE hard-deletes them.

​
Retrieve the verification

The moment an application pauses on its verification step, call POST /api/auto-apply/mailboxes/{id}/verification with the application_id. The call blocks while Jobo polls the inbox (newest messages first, read-only — your mail is never marked as seen) and an AI extractor picks the verification email using the application’s apply host and ATS provider as context, so a Greenhouse code isn’t confused with an unrelated login email that arrived the same minute. Providers verify in one of two ways — a one-time code to type into the form, or a confirmation link to click. The response’s type says which was found (constrain it by passing type: "code" or type: "link" in the request; the default any accepts either):
Every response carries a diagnostics block saying what the poll actually observed, so a timeout is explainable: messages_seen counts messages newer than the application that were visible at all, fetch_failures counts reads the mail provider failed transiently (skipped, not fatal), and extraction_failures counts rounds where the extraction model gave no usable answer while extraction_rejected counts rounds where it answered and nothing was accepted — last_extraction_reason names why the last such round came back empty (not_found, code_not_verbatim, …). A message is offered to the model more than once when a round produces no match, so a single off answer does not cost you the wait. On found, matched_by is llm, or pattern when the model spent its rounds on the message without a match and a strict provider-correlated pattern matched a one-time code. For type: "link" Jobo clicks the link server-side — https-only, public hosts only, bounded redirects — which confirms the address the way the applicant would. When link_visited is false the click failed; open the returned link yourself. A visited confirmation link is not by itself a terminal application result. Fetch the application and inspect status; only submitted confirms that the application completed. For code verification, submit the full current answer snapshot, including the code field and any other fields requiring answers. timeout is an expected outcome — the email may simply not have arrived — not an error. Real faults are RFC 7807 problems: mailbox_not_connected, mailbox_auth_failed (reconnect the mailbox), application_not_found, and mailbox_provider_unavailable (503 — the mail provider kept failing for the whole poll; retry shortly).
The one_time_code answer window is 90 seconds. Keep wait_seconds at the default 45 — or up to the 75 cap for a slow inbox — so there is time left to submit the code through the answers endpoint, and keep your HTTP client timeout above wait_seconds.
The extracted code is validated server-side: it must appear verbatim in the selected email. The response returns verification details and diagnostics, not the full email body.

​
Timing in practice

  1. POST /applications → application eventually pauses with a one_time_code field (the step’s answers_expire_at tells you the deadline).
  2. Immediately POST /mailboxes/{id}/verification with the application_id — the verification email typically lands within seconds of the step appearing.
  3. POST /applications/{id}/answers with the code as the field’s answer.
If the code expires before you submit it, the provider rejects it as verification_code_rejected and the application offers a correction round — read the current step and its new deadline before trying again. If the application is already terminal with verification_timeout, the old step cannot be resumed by submitting another code.