Email verification

Some ATS flows pause an application on an email verification step:

Code: the provider emails a one-time code, and current_step carries a field with format: "one_time_code" that expires in 90 seconds.
Link: the provider emails a confirmation link that must be clicked before the application counts as submitted.

Connecting a mailbox is optional. A verification code is an ordinary answer: if you already read the candidate’s inbox, submit the code through POST /api/auto-apply/applications/{id}/answers. These endpoints only save you building IMAP or OAuth inbox access, and you can use them for some mailboxes and not others.

With a mailbox connected, Jobo retrieves the code or visits the confirmation link. You still submit a code as an answer:

application pauses on one_time_code
        │
        ▼
POST /mailboxes/{id}/verification  ──▶ { status: "found", code: "AB12CD34" }
        │
        ▼
POST /applications/{id}/answers  (the code is just another answer)

Connect only a mailbox whose owner has authorized this access, on the same account as its applications.

Access

Every mailbox endpoint needs Jobo to have enabled Auto Apply for your account, even with a sandbox key. Jobo enables it when it approves your live access request. Until then, calls return 403 auto_apply_not_enabled: read emailed codes from the inbox yourself and submit them as answers.

Action	Sandbox key	Live key
List, read, and check mailboxes; retrieve verifications	Yes	Yes
Connect or delete a mailbox	No: `404 not_available_in_sandbox`	Yes

Mailboxes belong to the account, not to an environment: one connected with a live key also serves sandbox applications.

Connect a mailbox once

Connect each inbox once with POST /api/auto-apply/mailboxes, then pass its id for any application.

`provider`	Send	Create returns
`imap`	`address`, `imap_host`, and `password`	`status: "connected"`, or `422 mailbox_verification_failed` with nothing stored
`outlook`	`address`	`status: "pending"` and an `authorization_url`

curl --fail-with-body -X POST "https://connect.jobo.world/api/auto-apply/mailboxes" \
  -H "X-Api-Key: $JOBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"imap","address":"candidate@gmail.com","imap_host":"imap.gmail.com","password":"app-password"}'

For imap, use an app password where the provider offers one, such as Gmail. Create verifies the credentials before it returns. Optional fields: imap_port (993 or 143, default 993), imap_security (ssl or starttls, default ssl), and username (default: address). For outlook, open the authorization_url or send it to the mailbox owner. Sign in with the same address you declared, and the mailbox becomes connected. The link expires after 15 minutes; fetch the mailbox again for a fresh one. Outlook mailboxes are read over Microsoft Graph (delegated Mail.Read), so no IMAP host is needed or returned. A second mailbox with the same address returns 409 mailbox_already_exists. If a mailbox’s status becomes error, re-test it with POST /api/auto-apply/mailboxes/{id}/check before the next run. Secrets are encrypted at rest and never returned by any endpoint. DELETE hard-deletes them.

Retrieve the verification

As soon as an application pauses on its verification step, call POST /api/auto-apply/mailboxes/{id}/verification with its application_id:

curl --fail-with-body --max-time 90 -X POST \
  "https://connect.jobo.world/api/auto-apply/mailboxes/$MAILBOX_ID/verification" \
  -H "X-Api-Key: $JOBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"application_id\":\"$APPLICATION_ID\",\"wait_seconds\":45}"

Body field	Default	Values
`application_id`	Required	The application waiting on the email
`wait_seconds`	`45`	5 to 75; values outside the range are clamped
`type`	`any`	`code`, `link`, `confirmation` (a post-submit acknowledgment; no link is visited), or `any` (a code or a link)

The call blocks while Jobo polls the inbox, newest messages first. Polling is read-only, so no mail is marked as seen. An AI extractor picks the email using the application’s apply host and ATS provider, so a Greenhouse code isn’t confused with an unrelated login email from the same minute. The response’s type says what was found. A found code, a found link, and a timeout look like this:

{ "status": "found", "type": "code", "code": "AB12CD34",
  "email_from": "no-reply@greenhouse.io",
  "email_subject": "Your verification code", "waited_seconds": 9 }

{ "status": "found", "type": "link",
  "link": "https://boards.greenhouse.io/confirm?token=…",
  "link_visited": true, "link_http_status": 200, "waited_seconds": 11 }

{ "status": "timeout", "waited_seconds": 45,
  "diagnostics": { "searched_since": "2026-09-03T04:13:00Z",
    "folders": ["inbox", "junkemail"], "polls": 15, "fetch_failures": 0,
    "messages_seen": 0, "latest_message_received_at": null,
    "latest_message_from_domain": null, "latest_message_subject": null,
    "extraction_attempts": 0, "extraction_failures": 0,
    "extraction_rejected": 0, "last_extraction_reason": null } }

The one_time_code answer window is 90 seconds. Keep wait_seconds at the default 45, or at most the 75-second cap for a slow inbox, so there is time left to submit the code. Keep your HTTP client timeout above wait_seconds.

Codes and links are validated server-side and must appear verbatim in the selected email. The response carries verification details and diagnostics, never the full email body.

Links

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. If link_visited is false, the click failed: open the returned link yourself. A visited link is not a terminal result. Fetch the application and check status: only submitted confirms the application completed.

Diagnostics

Every response carries a diagnostics block describing what the poll saw, so a timeout is explainable:

Field	What it counts
`messages_seen`	Messages newer than the application that were visible at all
`fetch_failures`	Reads the mail provider failed transiently (skipped, not fatal)
`extraction_failures`	Rounds where the extraction model gave no usable answer
`extraction_rejected`	Rounds where the model answered but nothing was accepted
`last_extraction_reason`	Why the last such round came back empty (`not_found`, `code_not_verbatim`, …)

A message that produced no match gets more rounds, so one bad model answer does not end the wait. On found, matched_by is llm. It is pattern when the model used up its rounds on the message and a strict provider-correlated pattern matched a one-time code.

Timeouts and errors

timeout is an expected outcome, not an error: the email may not have arrived yet. Real faults are RFC 7807 problems:

Status	`code`	Next step
`409`	`mailbox_not_connected`	The mailbox is `pending` or `error`: finish the Outlook consent, or re-test it with `check`
`409`	`mailbox_auth_failed`	Credentials were rejected; reconnect the mailbox
`404`	`mailbox_not_found`, `application_not_found`	Check the IDs and the key’s account
`503`	`mailbox_provider_unavailable`	The mail provider kept failing for the whole poll; retry shortly

Timing

Create the application with POST /api/auto-apply/applications. When it pauses with a one_time_code field, the step’s answers_expire_at is your deadline.
Immediately call POST /api/auto-apply/mailboxes/{id}/verification with the application_id. The email usually lands within seconds of the step appearing.
Submit the code with POST /api/auto-apply/applications/{id}/answers, in the full answer snapshot for the step: the code field plus every other field that requires an 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, submitting another code cannot resume it.

Overview

Conventions

Jobs

Feed

Companies

Locations

Auto Apply

Access

Connect a mailbox once

Retrieve the verification

Links

Diagnostics

Timeouts and errors

Timing

​Access

​Connect a mailbox once

​Retrieve the verification

​Links

​Diagnostics

​Timeouts and errors

​Timing

Access

Connect a mailbox once

Retrieve the verification

Links

Diagnostics

Timeouts and errors

Timing