Metadata-Version: 2.5
Name: gucmail
Version: 1.2.0
Summary: An independent, security-focused terminal client for GUC Exchange mailboxes
Project-URL: Homepage, https://github.com/aynader/gucmail
Project-URL: Source, https://github.com/aynader/gucmail
Project-URL: Issues, https://github.com/aynader/gucmail/issues
Project-URL: Documentation, https://github.com/aynader/gucmail/tree/main/docs
Author: gucmail contributors
License-Expression: MIT
License-File: LICENSE
Keywords: email,ews,exchange,guc,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Email :: Email Clients (MUA)
Requires-Python: <3.15,>=3.11
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: cryptography<51,>=43
Requires-Dist: defusedxml<1,>=0.7
Requires-Dist: exchangelib==5.6.0
Requires-Dist: httpx<1,>=0.27
Requires-Dist: keyring<27,>=25
Requires-Dist: lxml<7,>=5
Requires-Dist: platformdirs<5,>=4.3
Requires-Dist: pyfiglet<2,>=1.0.2
Requires-Dist: python-dateutil<3,>=2.9
Requires-Dist: rapidfuzz<4,>=3.10
Requires-Dist: rich<15,>=13.9
Requires-Dist: textual<8,>=7.5
Requires-Dist: typer<0.28,>=0.15
Provides-Extra: attachments
Requires-Dist: openpyxl<4,>=3.1; extra == 'attachments'
Requires-Dist: pypdf<7,>=6.16.1; extra == 'attachments'
Requires-Dist: python-docx<2,>=1.1; extra == 'attachments'
Requires-Dist: python-pptx<2,>=1.0; extra == 'attachments'
Provides-Extra: desktop
Requires-Dist: plyer<3,>=2.1; extra == 'desktop'
Requires-Dist: windows-toasts==1.3.1; (sys_platform == 'win32') and extra == 'desktop'
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
Requires-Dist: mypy<2,>=1.14; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'dev'
Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
Requires-Dist: pytest-xdist<4,>=3.6; extra == 'dev'
Requires-Dist: pytest<10,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Requires-Dist: types-python-dateutil>=2.9; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: numpy==2.3.5; extra == 'semantic'
Description-Content-Type: text/markdown

# gucmail

Your GUC mailbox, in a terminal. Read, write, search, schedule and back up your mail without
opening Outlook on the web. Calendar, contacts and tasks come along too. Everything works from
the keyboard, and everything is scriptable.

![The Mail workspace: folders, inbox and an open message](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/mail.png)

It talks directly to the GUC Exchange server through Exchange Web Services (EWS), the same
interface Outlook uses, so there's nothing to install on the server and no third-party cloud in
between. Your password stays in Windows Credential Manager, and your mail stays on your machine:
gucmail fetches headers in small pages, loads a message only when you open it, and keeps a local
cache and search index you can wipe at any time.

It was made for GUC, but nothing in it is GUC-only. It works with any Exchange server that
offers EWS with a username and password, which covers most on-premises Exchange 2013–2019
installations. Point it at yours with `gucmail config set endpoint https://mail.example.edu/EWS/Exchange.asmx`.
Microsoft 365 isn't supported, because it only allows OAuth sign-in.

*This is an independent project. I am not affiliated with the German University in Cairo or Microsoft.*

## Install

You need Python 3.11 or newer. [pipx](https://pipx.pypa.io) installs gucmail in its own
environment and puts the `gucmail` command on your PATH:

```powershell
py -m pip install --user pipx
py -m pipx ensurepath                 # then open a new terminal
pipx install "gucmail[desktop]"
gucmail login                         # asks for your GUC password, stores it in Windows Credential Manager
gucmail tui                           # opens the full-screen interface
```

Update with `pipx upgrade gucmail`. Plain `pip install "gucmail[desktop]"` works too.
Leave out `[desktop]` if you don't want Windows notifications.

## Get around

![Arrowing through the inbox and opening messages](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/mail-browse-demo.gif)

Arrows move. **Enter** opens. **Tab** jumps between panes. **c** composes, **r** replies,
**/** searches and **?** shows every shortcut. Mouse and scroll wheel work too.

**Ctrl+K** opens the command palette. Type what you want in plain words:

![Typing "schedule this for tomorrow 9am" into the palette](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/palette-demo.gif)

It shows exactly what it understood (*Schedule current draft · tomorrow at 9:00*) and asks
before it does anything. It never guesses at deleting.

## Write

![The composer with recipients and an attachment](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/compose.png)

Reply, reply-all and forward. Cc and Bcc, attachments, signatures and importance. Recipients
autocomplete from your contacts and recent mail. It warns you about an empty subject, a missing
attachment you mentioned ("see attached…") or a typo in an address.

Drafts save themselves, and if your laptop dies mid-sentence, the draft is waiting next time.
**Undo Send** holds a message for a few seconds before it leaves.

## Send later

![The scheduled-mail queue](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/scheduled.png)

```powershell
gucmail send --to ta@example.edu --subject "Lab 6" --body-file report.txt --at "Monday 8:30"
gucmail send --to me@example.edu --subject "Reminder" --body "Submit thesis" --in "2 hours"
gucmail scheduled list
```

It always shows the exact time and time zone before queuing, refuses ambiguous dates like
`03/04`, and never sends anything twice. It handles Cairo's daylight-saving switch. Messages
go out from your PC, so it needs to be on. A Windows task can take care of that
([how](https://github.com/aynader/gucmail/blob/main/docs/scheduling/windows-task-scheduler.md)).

## Calendar, contacts, tasks

![The calendar week view](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/calendar.png)

Day, week, month and agenda views. Create events, accept or decline meetings, find a free
slot, catch clashes, and import or export `.ics` files.

| Contacts | Tasks |
|---|---|
| ![Contacts](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/contacts.png) | ![Tasks](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/tasks.png) |

Contacts find duplicates and merge them, and import and export vCards. Tasks have due dates,
progress and repeats.

## Search

```powershell
gucmail search --sender "dr. mona" --after 2026-10-01 --has-attachments
gucmail search "rubric" --all-folders
gucmail index build --include-bodies             # build a local full-text index once…
gucmail search --local --fuzzy "gradng rubrik"   # …then search it offline, typos and all
```

Saved searches, per-folder or whole-mailbox scope, and a search box in every view.

## Notifications, even with the terminal closed

A small background watcher checks your Inbox about once a minute and shows a Windows toast
for new mail. It runs as a Windows task that starts when you sign in, with no window and no
terminal. Clicking a toast opens the message.

In the interface: press **Ctrl+K** and open **notification settings**.

1. Choose **New / setup** to create a monitoring profile for your Inbox, then **Enable** it.
2. Under **Providers & Privacy**, choose **Desktop setup…**, then **Add provider → Desktop**.
3. Go to **Settings**, search for **start**, and choose **Start monitoring with Windows →
   Open setup**. Your active profile is filled in. Press **Enable…** and monitoring starts
   straight away, then again every time you sign in.

Or from the command line:

```powershell
gucmail notifications profiles create primary --name "Inbox" --enabled --activate
gucmail notifications desktop setup --apply          # lets Windows show gucmail toasts
gucmail startup enable --profile primary --apply     # the background task
```

The Desktop provider is added in the interface, as above. Quiet hours, rules ("only mail
from @guc.edu.eg with 'exam' in the subject") and signed webhooks are optional.
[Details](https://github.com/aynader/gucmail/blob/main/docs/monitoring/headless-deployment.md).

## Backups you can read without a connection

![The Backup Center](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/backups.png)

```powershell
gucmail backup create --encrypt          # full backup, password-protected
gucmail backup incremental               # just what changed since
gucmail backup browse <id>               # read it offline, even with Wi-Fi off
gucmail tui --offline                    # or browse cached mail in the interface
```

Backups never mark anything read and never change the server. Restores are planned first,
with exact counts, and you confirm before anything is written.

## Make it yours

![The theme picker](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/themes.png)

More than 600 themes with live preview, and your own colours or logo. Choose your columns,
layouts and keyboard shortcuts in Settings, which you can search.

![Settings](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/settings.png)

## Scripts and automation

Every command has `--json` (one envelope) or `--ndjson` (one record per line), stable exit
codes, `--yes` for confirmations and `--dry-run` for anything that changes mail.

```powershell
gucmail --json messages list --folder inbox --limit 5
gucmail --ndjson search --unread | ConvertFrom-Json | ? type -eq item | % { $_.data.subject }
gucmail --yes messages move msg_12 msg_13 --to "Courses/Distributed Systems"
gucmail quota                              # how full your mailbox is
gucmail doctor                             # checks everything, offline unless you ask
```

There's more under `gucmail --help`: rules, automatic replies, insights ("who fills my
mailbox?"), cleanup plans, clustering and an EWS capability browser.

## Good to know

- Some features depend on what GUC lets your account do: the directory, free/busy, rules,
  delegates and quota limits. When the server says no, gucmail tells you so and never
  invents a value.
- It's tested on Windows 11. Linux and macOS should work but aren't tested yet.
- More: [user guide](https://github.com/aynader/gucmail/blob/main/docs/user-guide/index.md) ·
  [all commands](https://github.com/aynader/gucmail/blob/main/docs/command-reference/index.md) ·
  [troubleshooting](https://github.com/aynader/gucmail/blob/main/docs/troubleshooting/index.md) ·
  [privacy & security](https://github.com/aynader/gucmail/blob/main/docs/privacy-and-security/index.md) ·
  [known limits](https://github.com/aynader/gucmail/blob/main/docs/STATUS.md)

## Licence

MIT. See [LICENSE](https://github.com/aynader/gucmail/blob/main/LICENSE).
