# Mail intake bot - ops handover

Version: none shown by the bot (code as of commit 07255fa) · Written 2026-10-23 · Escalation: raise a ticket in the **RPA Support** queue

## 1. What the bot does

Every 10 minutes, Windows Task Scheduler starts the bot. It reads the **unread** emails in the referrals mailbox and saves every attachment. It checks that each attachment is a PDF under 20 MB, then copies it into the **shared intake folder**. That folder is the only output, and the only place ops can see. The bot keeps an internal queue with a status and a note for every attachment. Ops cannot open that queue or the bot's log (see section 5). The bot drives no desktop apps or websites, so no windows need to be left alone. It talks only to the mailbox and the shared folder.

## 2. How it works

```
Windows Task Scheduler (every 10 min)
   └─ starts → Mail intake bot ──reads──> Referrals mailbox (unread mail only)
                     │
                     ├─ saves attachments → the bot's own temp folder
                     ├─ copies good PDFs → Shared intake folder   ← ops can see this
                     ├─ writes → internal queue (status + note per attachment)   ← ops cannot see
                     └─ writes → bot log file                                     ← ops cannot see
```

- **Task Scheduler** starts the bot every 10 minutes. The bot has no window and no screen.
- **Referrals mailbox:** the bot signs in and takes every unread email. When it reads an email, the mailbox marks it as read.
- **Temp folder:** every attachment lands here first. Rejected or failed files **stay here**, not in the intake folder.
- **Shared intake folder:** only PDFs that passed the checks and copied correctly end up here.
- **Internal queue and log:** they hold the status, the reason and the time of each item. Only the dev team can open them today.

**One run, step by step:**
1. If an item from an earlier run is still marked "Processing", the bot **stops straight away** and does nothing more in this run (see E01).
2. It signs in to the mailbox. If that fails, it tries up to 3 times, 30 seconds apart.
3. It takes all unread emails, saves every attachment to the temp folder and adds each one to the queue as "New".
4. For each New item: it marks the item Processing, checks the file, copies it to the intake folder, then sets the item's final status and note.

## 3. Before a run

Ops cannot check these items. The dev team sets them up. They are listed here so ops knows what a "nothing arrives" ticket can be about.

- [ ] (Dev) The bot's settings file has the mailbox address, user and password, and the intake folder location. If one is missing, every run crashes at start and writes **nothing** to the log.
- [ ] (Dev) The bot's data folder holds the queue and a temp folder. On the current machine the data folder is empty, so the first run would crash.
- [ ] (Dev) The mailbox password has not expired. An expired password stops all intake (E02).
- [ ] (Dev) The scheduled task is enabled and runs every 10 minutes.
- [ ] Rules for referral senders, which ops can pass on:
  - Send each referral as a **PDF**, **under 20 MB**, **without a password**.
    - Bad: `referral.docx`, a 35 MB scan, a password-protected PDF. Good: `referral.pdf`, 3 MB, opens without a password.
  - Give every file a **unique name**. Two attachments with the same name overwrite each other (E06).
    - Bad: two emails that both attach `scan.pdf`. Good: `scan_<date>_<number>.pdf`.
  - Logos and pictures in an email signature also count as attachments. They are rejected as "not a PDF", which is harmless.

## 4. During a run

- There is nothing to watch. The bot has no window.
- **Do not mark emails in the referrals mailbox as read.** The bot only picks up unread mail. An email marked read by hand is never processed.
- **Do not move, rename or open-and-lock files in the intake folder while they are being copied.**
- To stop the bot: ops cannot. Raise an RPA Support ticket and ask the dev team to **disable the scheduled task between runs**. Never end the bot in the middle of a run. A run killed halfway leaves an item in "Processing", and that blocks every later run (E01).
- How a stuck bot looks: **no new files arrive in the intake folder for more than 30 minutes while referrals are being sent.** The bot does not restart itself and has no stuck-run limit. It stays blocked until the dev team acts, so raise a ticket straight away.

## 5. Where to look when something goes wrong

Ops can open the shared intake folder and nothing else. The bot has no screen or report of its own. Most answers are therefore "raise a ticket". Section 13 lists the gaps for the dev team.

| Question | Where to look |
|---|---|
| Did the run finish? | Ops cannot see this. The only sign is new files in the intake folder, sorted by date modified. |
| Is the bot working at all? | Intake folder: was the newest file added in the last 30 minutes (during hours when referrals come in)? If not, raise a ticket. |
| Did a particular referral arrive? | Intake folder: look for the attachment's file name. If it is missing, raise a ticket with the email's received time. |
| Why did one item fail? | Ops cannot see this. The status and note are only in the bot's queue and log. Raise a ticket. |
| Did the bot already retry? | It only retries signing in to the mailbox (3 tries, 30 seconds apart, every run). Nothing else is retried (section 8). |
| Which version is running? | Not shown anywhere (section 10). |

## 6. Statuses

The bot gives every attachment one status and one note. **No screen shows them to ops and they have no colour.** Only the dev team can read them. They are listed so ops and dev use the same words in a ticket.

| Status | Note written | Colour | Meaning | What ops does |
|---|---|---|---|---|
| New | (empty) | none (not shown) | Saved from the mailbox, waiting for this run's checks | nothing |
| Processing | (empty) | none (not shown) | Being checked and copied right now. **If it is still there after the run, it blocks every later run.** | Ticket if no new files arrive for 30 minutes (E01) |
| Done | "<n> pages saved" | none (not shown) | PDF copied to the intake folder | nothing |
| Done | "encrypted - not readable" | none (not shown) | **Needs follow-up.** A password-protected PDF. It was **not** copied to the intake folder, even though the status says Done. | Ask the sender to resend it without a password (E05) |
| Quarantined | "not a PDF or over 20 MB" | none (not shown) | Rejected. It stays in the bot's temp folder and is not copied. | Ask the sender to resend it as a PDF under 20 MB (E04) |
| Failed | "share unreachable: <error>" | none (not shown) | The intake folder could not be reached. **Never retried.** | Ticket. The dev team must re-queue it (E03). |

## 7. Exception catalogue

Ops sees most of these the same way: **a file is missing from the intake folder.** Quote the E-number in the ticket when you know it. When you don't, say "no new files since <time>".

| ID | What you see | How the bot identifies it | Where it is recorded | Type | Who acts | What to do | Escalate when |
|---|---|---|---|---|---|---|---|
| E01 | No new files in the intake folder at all, for 30 minutes or longer | At start, the bot finds an item still marked Processing from an earlier run, which crashed or was stopped. It stops at once, every run, until someone clears that item. | Bot log: "Previous item still Processing - aborting", once every 10 minutes. Not visible to ops. | System | Dev | Raise a ticket. Send: when the last file arrived in the intake folder, and the time you noticed. Dev must check whether the blocked file **is already in the intake folder** before re-queuing it, otherwise it is copied twice. | Always. It never clears by itself. |
| E02 | No new files in the intake folder at all | Signing in to the mailbox fails 3 times, 30 seconds apart (wrong or expired password, or the mailbox server cannot be reached). The run then crashes. | Bot log: "IMAP connect failed (1/3)" … "(3/3)" every run. The final crash is not logged. Not visible to ops. | System | Bot, then Dev | Wait 10 minutes for the next run. If still nothing arrives, raise a ticket: "no new files since <time>, possibly mailbox sign-in". | No files for 30 minutes |
| E03 | One referral's PDF is missing from the intake folder, while others still arrive | Copying to the intake folder fails (the folder is unreachable, full, or the file is locked). | Status Failed, note "share unreachable: …". Not visible to ops. | System | Dev | Raise a ticket with the email's received time and the attachment's file name. The dev team copies it or re-queues it. **The bot never retries it.** | Always |
| E04 | One referral's attachment is missing from the intake folder | The attachment is not a .pdf file, or it is over 20 MB. | Status Quarantined, note "not a PDF or over 20 MB". It stays in the bot's temp folder. Not visible to ops. | Business | Ops (after dev confirms) | Ask the sender to resend it as a PDF under 20 MB, in a **new** email. | The file is a PDF under 20 MB and was still rejected |
| E05 | One referral's PDF is missing from the intake folder, but the bot reports it as Done | The PDF is password-protected. | Status **Done**, note "encrypted - not readable". Not visible to ops. | Business | Ops (after dev confirms) | Ask the sender to resend it without a password, in a new email. | Never. This is a known gap (section 13). |
| E06 | A file in the intake folder has the right name but the wrong content, or a referral seems to be missing | Not detected. Two attachments with the same file name overwrite each other in the temp folder and in the intake folder. | Nowhere. Both queue items show Done. | Business | Dev | Raise a ticket with the file name and the received times of both emails. Ask the senders to use unique file names. | Always |
| E07 | No new files at all (it then turns into E01) | Not detected. A damaged or fake PDF makes the bot crash while it reads the file. The item stays Processing. | Nowhere. The crash is not logged, and from the next run the log shows E01's line. | System | Dev | Same as E01. In the ticket, mention any referral that arrived just before files stopped. | Always |
| E08 | A referral email is never processed, and it shows as **read** in the mailbox | Not detected. The bot marks emails read as it fetches them. If it crashes before the email reaches the queue (an empty or unusual attachment, a missing temp folder), the email is lost. | Nowhere. Not in the queue, not in the log. | System | Dev | Raise a ticket with the email's received time. The dev team marks it unread so the next run picks it up. | Always |
| E09 | No new files at all, from the very first run or right after a change on the bot machine | Not detected. A setting is missing (mailbox details, intake folder location) or the bot's data folder or queue is missing, so the bot crashes at start. | Nowhere. The crash happens before anything is logged. | System | Dev | Raise a ticket: "no files since <time>, after <change, if known>". | Always |
| E10 | No new files at all, and the problem lasts for hours | Not detected. Sign-in or copying hangs with no time limit, so the run never ends. Task Scheduler does not start new runs while one is still running. | Nowhere | System | Dev | Raise a ticket. The dev team ends the hung run, then checks for a Processing item (E01). | Always |

Never send in a ticket or chat: patient names, referral contents, the PDF itself, mailbox passwords or the bot's settings file. Use the received time and the file name.

## 8. What the bot recovers by itself

| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| Can't sign in to the mailbox | Tries again after 30 seconds | 3 tries per run (about 1.5 minutes) | The run crashes. The next run, 10 minutes later, tries again, and that repeats forever with no alert (E02). |
| Intake folder unreachable | Nothing. No retry. | - | Item Failed for good (E03) |
| Item left in Processing | Nothing. No retry. | - | Every run stops until the dev team clears it (E01) |
| Run hangs | Nothing. No watchdog. | - | Blocked until the dev team ends it (E10) |

Ops never needs to wait more than **one run (10 minutes)** before acting. Apart from mailbox sign-in, the bot does not fix anything by itself.

## 9. Known incidents

Dates come from the commit history (all recorded 2026-10-23) and the bot log (2026-09-04). The bot has no version numbers.

| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| Recorded 2026-10-23 | Nothing arrived for days. Every run failed silently. | The mailbox password expired. Sign-in failures were not logged. | Sign-in failures are now logged (E02), but there is still no alert and ops cannot see the log. Raise a ticket after 30 minutes with no files. | Partly. Ops can spot "no files", not the cause. |
| Recorded 2026-10-23 | Password-protected referrals reached the intake folder as empty copies | The bot copied PDFs it could not read | They are now **not copied at all** and marked Done "encrypted - not readable" (E05). Still invisible to ops. | Partly. Ops can ask senders not to use passwords. |
| Recorded 2026-10-23 | No referrals arrived for a whole working day | A crash left one item in Processing, which blocked every run. Ops reset it by hand. | **Not fixed in the code.** It still happens (E01, E07). Raise a ticket after 30 minutes with no files. | Partly. Spotting it, yes. Ops can no longer clear it, because they have no access to the queue. |
| 2026-09-04 (log) | Files stopped at about 08:00 | The mailbox server could not be found, then an item was left in Processing and blocked the following runs | As E02 and E01 | Partly |

## 10. Releases and version check

- How an update arrives: not defined in the code. There is no launcher, no installer and no version number. The dev team changes the code on the bot machine.
- How to confirm it applied: ops cannot. The bot does not show its version anywhere.
- If you suspect an update did not apply (a fixed problem comes back), raise a ticket naming the incident from section 9.

## 11. Escalating to dev

Raise a ticket in the **RPA Support** queue.

Send: the E-number from section 7 if you know it, when the last good file appeared in the intake folder, when you noticed, and for a single missing referral the email's received time and the attachment's file name.
Never send: passwords, the bot's settings file, the referral PDF, or patient or customer details in the ticket or chat.

## 12. Failure-class check

- F1 Missing prerequisite: covered in section 3 (Dev checklist) and E09. Section 13 items 4 and 5.
- F2 Wrong window / focus: not applicable. The bot drives no windows or apps, only the mailbox and a file share.
- F3 Target slower or different: covered in E02, E10 and section 8. Section 13 item 6 (no time limits).
- F4 Input read differently: covered by the sender rules in section 3 (PDF, 20 MB, no password, unique names) and E04, E06. Section 13 items 7 and 8.
- F5 Marked done when nothing was done: covered in E05 and E08. Section 13 items 2 and 9.
- F6 Action happened but not confirmed: covered in E01 ("check the file is already in the intake folder before re-queuing").
- F7 Business exception shown as success: covered in section 6 (Done "encrypted - not readable") and E05. Section 13 item 2.
- F8 Endless re-runs / watchdog: covered in section 8 (endless mailbox retries every 10 minutes, no watchdog) and E10. Section 13 item 6.
- F9 Stopping the wrong way: covered in section 4 (disable the scheduled task between runs; never kill a run midway).
- F10 One stuck item blocks the queue: covered in E01 and E07, section 4, section 8. Section 13 item 1.
- F11 Cause hidden from ops: covered in section 5. Section 13 item 3.
- F12 Update didn't arrive: covered in section 10. Section 13 item 10.

## 13. Fix before handover (dev team)

| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | One item left in "Processing" stops every later run, with no time limit and no auto-reset. The commit "fix: worker blocked…" (c4765ff) only added a comment and changed no code. Any crash in `process()` (a damaged PDF in `PdfReader`, a missing temp file in `stat()`) causes it. | Intake stops for good and ops can neither see it nor clear it | `intake.py:74-76`, `intake.py:61`, `intake.py:79-83`, `intake.py:89` |
| 2 | Encrypted PDFs get status **Done** but are not copied | A referral is silently missing while its status says Done | `intake.py:62-63` |
| 3 | Statuses, notes and the log are visible only to dev. The README's `queue_viewer.xlsx` does not exist in the repo and nothing creates it. Ops has no screen and no access to the database or logs. | Ops cannot tell which item failed or why, and can only report "no files" | `README.md:6`, `intake.py:23-24`, `intake.py:82` |
| 4 | Uncaught crashes are not logged (sign-in exhausted `RuntimeError`, missing `.env` key `KeyError`, missing `queue` table, `PdfReader` errors). There is no alert of any kind. | Silent outages, as in the expired-password incident | `intake.py:37`, `intake.py:31-32`, `intake.py:71-88` |
| 5 | `data/` is empty on this machine. Nothing creates `data/tmp` or the `queue` table. | The first run crashes (E09) | `intake.py:17-18`, `intake.py:50-52`, `intake.py:73` |
| 6 | No timeout on the IMAP connection or the share copy | A hung run blocks all later runs with no limit (E10) | `intake.py:31`, `intake.py:65` |
| 7 | The attachment file name from the email is used as-is. Same names overwrite each other in tmp and on the share, and names containing `..\` can write outside the temp folder (security). | Lost or overwritten referrals (E06), plus a path-traversal risk | `intake.py:47-51`, `intake.py:65` |
| 8 | Signature images and other inline attachments are queued and Quarantined | Noise in the queue that hides real rejections | `intake.py:46-49`, `intake.py:59-60` |
| 9 | Emails are marked read when fetched, but the queue is committed only after all of them. A crash in between (e.g. `get_payload` returning None) loses the email. | Referrals lost with no record (E08) | `intake.py:42-54` |
| 10 | No version string and no defined update process. The three "fix" commits changed only comments, so the history does not show what is actually fixed. | Nobody can confirm which build runs or that a fix arrived | `intake.py:89-91`, whole repo |
| 11 | `Failed` items are never retried. Only `New` is picked up. | One share outage loses those referrals until dev re-queues them | `intake.py:66-67`, `intake.py:78` |
| 12 | `.env` (mailbox credentials) and `logs/intake.log` are committed to git, and the committed log contains a sender email address | Credentials and personal data sit in the repo history | `.env`, `logs/intake.log:6` |