Export Bookkeeper emails to Excel
Four steps, one command, and a completeness check at the end — for client correspondence kept per client folder.
Step 1 — connect read-only
Use an app password, never the main password. The script opens the folder in read-only mode, so nothing is marked as read or deleted.
python mail_to_excel.py --host imap.example.com --user you@example.com --days 31 --fields client,period,amount,category,receipt --out bookkeeper.xlsxStep 2 — filter to one period
A month or a quarter, not «everything». Clients send receipts and approvals in different threads. One table per period beats forty folders nobody opens.
Step 3 — keep only the columns that matter
| Column | Why it matters |
|---|---|
client | The join key for every other report you will build later. |
period | Month or quarter, so each export is a closed, auditable slice. |
amount | Store as a number with a separate currency column; never sum mixed currencies. |
category | Bookkeeping category, assigned once and reused across periods. |
receipt | File name of the saved attachment — the audit trail. |
Step 4 — verify completeness
- Run the same search in your mail client and note the message count.
- Compare it with the row count in the spreadsheet.
- If the numbers differ, the filter or the folder is wrong — fix it before using the file.
Example output
| client | period | amount | category | receipt |
|---|---|---|---|---|
| Northwind LLC | 2026-09 | 3,120.00 | software | receipt-0912.pdf |
Pitfalls
- Client names are spelled differently in every email — Normalise on the email domain, then map domains to client names once in a lookup sheet.
- Receipts are missing for some rows — Leave the receipt column empty instead of guessing — the empty cell is your to-do list.
Provider notes
Yandex and Mail.ru require an app password, and IMAP must be enabled in the mailbox settings first.
FAQ
Can I export several clients at once?
Yes, if each client has its own folder or label. One IMAP run per folder keeps the client column reliable.
What about scanned receipts?
The export lists them; reading the amounts needs OCR, which is a separate step.
How many messages can it handle?
Thousands per run with a date filter; very large mailboxes are better exported month by month.
Will it change anything in the mailbox?
No. Read-only access is the default and should stay enabled.
Related guides
- Bookkeeper: columns and pitfallsThe compact overview for this role.
- Universal IMAP guideApp passwords, decoding and Excel output.