Loading…
Loading…
about 45 minutes of your work, and you need to be (or sit next to) an administrator of your Microsoft 365 account for the key partNo experience assumed: the guide starts at "install Python".
Using an AI assistant? Let it do the busywork.
Claude Code, Cursor, Copilot: paste this prompt and your own AI handles the installing, checking and scheduling, on your machine. You keep the key steps.
The prompt forbids your assistant from asking for keys in chat, and from ever touching the push side: you create credentials yourself, and changes always need your typed YES.
Unzip your download and put the toolkit folder somewhere easy to find. Inside are two folders that stay strictly apart: pull, which can only read (the daily snapshot plus five live lookup scripts), and push, which really changes things (tasks, drafts, sends, calendar events) and always asks you to type YES first.
You only need the push folder if you want the toolkit to make approved changes. Pulling your daily snapshot works fine without it.
The toolkit runs on Python, a free program. You need version 3.9 or newer from https://www.python.org/downloads/ and installing it takes a few minutes.
On Windows, do not skip the Add python.exe to PATH checkbox during install. Without it your computer will not know what the python command means.
The scripts need one helper package, installed one time in each script folder. First open a terminal in the pull folder, then run the install command. If you use the push folder, do the same there.
In a terminal in the pull folder
pip install -r requirements.txtMicrosoft calls an API key an app registration: a key with a permission list attached. No software is installed anywhere. You create one read-only app for the pull folder. The full click-by-click walk is in pull/azure-setup-guide.md, and here is the path.
In the app's menu, choose API permissions, then + Add a permission, then Microsoft Graph, then Application permissions. Tick the 15 read-only permissions below (use the search box; tick, then search the next one, your ticks are kept). Then click Add permissions, then Grant admin consent for your organization, and confirm. Every row must now show a green check mark.
Always choose Application permissions, never Delegated permissions. The scripts run on their own, without a signed-in user, and picking Delegated is the most common wrong turn. And do not forget Grant admin consent: without the green check marks the scripts get 403 Forbidden.
If you never use Teams, SharePoint, or meetings, you can leave those permissions out. That part of the pull then reports a clear not-consented note and everything else still runs. verify_auth.py will list any missing permission by name.
Now create the key itself. In the app's menu choose Certificates and secrets, then + New client secret, give it a description and a lifetime, and click Add.
The secret's Value is shown only once, right after you create it. If you navigate away without copying it, simply create a new secret.
Only do this if you use the push folder. Repeat the registration step with a different name, for example graph-toolkit-write. Then in API permissions add these 5 Application permissions, click Grant admin consent, and create its own client secret the same way as before.
Never reuse the read app's key for the push folder or the other way around. Two apps means you can revoke the write key without losing your daily data pull.
Now give the scripts your keys. In the pull folder, copy .env.example to a new file named .env in the same folder. Never share this file.
Recommended by the toolkit's azure-setup-guide (step 7): a mailbox fence plus a canary mailbox, so the keys can only ever touch the mailboxes you chose. It is a one-time PowerShell job for your administrator, and verify_auth.py then proves the fence is holding.
Time for the first real test. Open a terminal in the pull folder and run the check below. It checks your keys, permissions, every board and mailbox, and changes nothing. A good result prints the line OK | credentials valid. If you use push, run the same command in the push folder; a good result there ends with All checks green. Zero mutating calls were made.
In the pull folder
python verify_auth.pyThe most likely failure is SETUP NEEDED, which simply means a line in .env still needs your real value. The message names exactly which one. A 403 Forbidden usually means admin consent is not granted yet, or not propagated yet: wait about 15 minutes and run the check again.
Still in the terminal in the pull folder: first a small test run, then the real thing. The last line of a healthy run reads Done. N CSVs written, 0 fail/empty/partial.
Small test run first
python pull_microsoft_graph.py --smokeThe real thing
python pull_microsoft_graph.pyThe small test run writes its own set of CSVs into the same output folder as the real run. Once the real pull succeeds, delete the test run's files (the set with the earlier time in the filename) so you never mistake the tiny test for your real data.
If the script seems to pause mid-run, that is normal. Microsoft rate-limits busy accounts, and the script waits exactly as long as asked and retries by itself. Let it finish.
Let your computer do the daily run for you. The script itself makes sure a day is never pulled twice.
Only ever automate the pull script. Never automate push: pushing deserves human eyes every time, and its YES gate refuses schedulers on purpose.
Where your CSVs land. Every run writes dated CSV files into the output folder inside the pull folder, right next to the pull script. Those are the files you open in Excel or drop into Toqool Local. A whole run shares one timestamp so it sorts together, files are never overwritten, and an incomplete file is clearly marked PARTIAL so it can never be mistaken for a complete one.
Stuck on any step? Mail us at support@toqool.com and a founder answers.