Docs & help

Short answers, one topic per card. The same help lives inside the app (Help tab) — this copy is here so you can read it before installing.

Get set up Add an account Pick an AI Telegram Act from your phone Button glossary Newsletters Troubleshooting Privacy

🚀 First-time setup — four steps

Install — download, unzip anywhere, double-click MaiElf.exe.
Windows may show a SmartScreen warning the first time — it doesn't know small apps. Click More info → Run anyway.
Add accounts — Accounts tab. Provider → email + password → Test & add. Lots of accounts? Import from CSV.
Pick your AI — Settings. Default is Ollama (free, local, private) or paste an OpenAI / Claude / Gemini key. 🧪 Test AI confirms.
Connect Telegram + automate — free bot from @BotFather, then Install schedule: polls every 15 minutes, digests morning and evening.

📮 Adding accounts — by provider

Gmail
Needs an app password, not your normal one.
Turn on 2-Step Verification, then go to myaccount.google.com/apppasswords.

Yahoo
Also an app password: Yahoo account security → Generate app password.

Outlook / Hotmail / Microsoft 365
Pick the Microsoft provider. Invent a NEW password just for MAIElf (not your Microsoft one). Click Set up Microsoft sign-in, finish in the browser tab that opens, then Test & add.
To also SEND from this account, redo the sign-in once — sending needs one extra permission.

Titan (Hostinger) & Purelymail
Your normal mailbox password works.

Anything else with IMAP
Choose Custom and enter the server address from your provider's help page.

🤖 Choosing your AI

Ollama (default) — free, runs on your PC, mail never leaves it.
Install from ollama.com/download, then run:
ollama pull qwen2.5:7b-instruct

Cloud — OpenAI, Claude, Gemini, Grok, DeepSeek, Groq, OpenRouter.
The hint under the dropdown says exactly where to create each key.

📲 Telegram — alerts and the two-way assistant

Alerts ping instantly for client leads, money, security codes, VIP senders. Digests arrive morning and evening.

The assistant answers back — text your bot:

/urgent — anything urgent in the last 24h
/report — mini digest of what you missed
/waiting — who hasn't replied to your mail
/search stripe invoices
summarize the last 5 emails from John about the hike, action list
book a meeting Tuesday at 8 with John and Mike — tap-to-add calendar file
email dana about moving the call to Friday — sends only after you confirm

🎯 Acting by number from your phone

Whenever the bot shows a numbered list (the digest, /urgent, /report, /search), text back the number + what to do. Say item 2 is Dana's email:

done 2 — mark it handled; gone from the queue.

snooze 2 3d — hide it for 3 days, then it returns. (snooze 2 = 1 day, 0.5 = half a day)

mute 2 — that sender never alerts again. For noisy robots, not people.

reply 2: sounds good, Friday works — becomes a real email reply. The bot shows exactly what will send and sends only after you answer yes.

Numbers stay valid until the bot shows a new list, which renumbers.

🔘 What every button does

Colors say what a button does: green = safe · gold = sender status · orange = moves/pauses · blue = time & AI · red = deletes.

Needs attention
📧 View	read the real email, attachments included
Open ↗	jump to it in that account's webmail
Draft	AI writes a reply from the whole thread
📤 Send	send the draft — you confirm to/subject first
Done	handled; leaves the queue
💤	snooze until later; comes back by itself
⭐	VIP — this sender always alerts you
🔇	mute — this sender never alerts again
✉️ Compose	new email from any account; 🪄 Write it = AI drafts it
Unsubscribe center
⚡ 1-click	unsubscribe silently in the background
Unsubscribe ↗	open the sender's unsubscribe page
Sweep	move their mail to an MAIElf-swept folder — never deleted
Keep	leave this sender alone
🗑 Delete messages from sender	move their whole history to that account's Trash (opt-in)
Accounts
Test	check the login still works
Unsync	pause syncing this mailbox — nothing deleted
Remove	remove from MAIElf — the mailbox itself untouched

🧹 Taming newsletters — the ladder

Keep — it's fine, leave it.
Sweep — hide the pile in an MAIElf-swept folder. Nothing deleted. New mail still arrives until you unsubscribe.
Unsubscribe — stop future mail (⚡ 1-click is silent).
🗑 Delete — move everything from that sender to the account's own Trash. Off by default; recoverable from Trash until your provider empties it.

Handled senders fold into a collapsed ✓ section so the working list stays short.

🛠 Troubleshooting

Symptom	Fix
Windows warns on install	SmartScreen doesn't know small apps — More info → Run anyway
Something looks stale	Double-click `MaiElf.bat` — restarts everything fresh
A job seems stuck	Settings › Automation shows a live log of what's happening
No Telegram alerts	Settings › Telegram › Send test message; token and chat must both be green
AI errors	Settings › 🧪 Test AI. Ollama: is the Ollama app running? Cloud: re-check the key
Account dot is red	Password expired or token revoked — Accounts › Test shows the exact error
Gmail login fails	You need an app password (see Adding accounts above), not your normal one
Mail piling up unclassified	The AI engine is down — you also get one Telegram warning about it

Still stuck? hello@maielf.com

🔐 Privacy & security

Passwords, tokens, and keys are encrypted with Windows DPAPI — tied to your Windows login. A stolen disk yields ciphertext.
Stored email bodies are encrypted in the local database too.
With Ollama, mail content never leaves your machine — except the alert/digest text sent to your own Telegram bot.
With a cloud AI, message text goes to that provider for analysis.
The dashboard listens only on your computer (127.0.0.1).
Nothing is moved, deleted, or sent unless you click the button for it.