{"id":13426030,"url":"https://github.com/Oxygem/Kanmail","last_synced_at":"2025-03-15T20:31:50.548Z","repository":{"id":41369366,"uuid":"141852287","full_name":"Oxygem/Kanmail","owner":"Oxygem","description":":inbox_tray: An email client that functions like a kanban board.","archived":false,"fork":false,"pushed_at":"2023-04-25T07:53:06.000Z","size":6343,"stargazers_count":1298,"open_issues_count":50,"forks_count":89,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-10-28T04:25:14.367Z","etag":null,"topics":["desktop-app","email","imap","imap-client","javascript","python","react"],"latest_commit_sha":null,"homepage":"https://kanmail.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Oxygem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"custom":["https://kanmail.io/license?ref=github"]}},"created_at":"2018-07-21T23:27:23.000Z","updated_at":"2024-10-25T04:03:03.000Z","dependencies_parsed_at":"2022-07-08T05:32:18.934Z","dependency_job_id":null,"html_url":"https://github.com/Oxygem/Kanmail","commit_stats":null,"previous_names":[],"tags_count":98,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oxygem%2FKanmail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oxygem%2FKanmail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oxygem%2FKanmail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oxygem%2FKanmail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Oxygem","download_url":"https://codeload.github.com/Oxygem/Kanmail/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243790939,"owners_count":20348378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop-app","email","imap","imap-client","javascript","python","react"],"created_at":"2024-07-31T00:01:24.667Z","updated_at":"2025-03-15T20:31:45.515Z","avatar_url":"https://github.com/Oxygem.png","language":"JavaScript","funding_links":["https://kanmail.io/license?ref=github"],"categories":["JavaScript","Go"],"sub_categories":[],"readme":"\u003ch1\u003e\n    \u003cimg src=\"./kanmail/client/icon.png\" width=\"28px\" /\u003e\n    Kanmail\n\u003c/h1\u003e\n\n\u003e Hey there 👋, I'm Nick and I build \u0026 maintain Kanmail. Life is very busy these days with a (very) young family so Kanmail development tends to be inconsistent. I still use Kanmail every day and will continue to fix bugs, improve performance and build features. \n\nAn email client that functions like a kanban board, for Mac/Windows/Docker. [**Download the latest release here**](https://kanmail.io/download).\n\n![](./screenshot.png)\n\n+ Works on MacOS, Windows \u0026 Docker (see [Linux support issue](https://github.com/Oxygem/Kanmail/issues/140))\n+ Developed using Gmail, Outlook \u0026 Fastmail\n+ Should be compatible with [other email providers](https://kanmail.io/docs/email-providers) (uses IMAP/SMTP)\n+ Considered in \"beta\" - used as primary email client for \u003e1yr\n\nThe rest of this readme focuses on the technical details of Kanmail. For user documentation [**see the Kanmail website**](https://kanmail.io/docs).\n\n## License\n\nBefore continuing it is important to note that Kanmail is **source available but not free**. Kanmail is available for free download for evaluation; for continued use of Kanmail a [**license should be purchased**](https://kanmail.io/license).\n\nWe welcome pull requests, but note you will be contributing to a non-free project. You will be required to sign [the Oxygem CLA](https://gist.github.com/Fizzadar/6093499cccdcac7a4d83698516f9cafa) before any contributions can be merged. We offer free license keys to contributors, please email [hello@oxygem.com](mailto:hello@oxygem.com) for more information.\n\n+ [License](#license)\n+ [Development](#development)\n    * [Setup your system](#setup-your-system)\n    * [Install requirements](#install-requirements)\n    * [Start the app](#start-the-app)\n+ [Building](#building)\n    * [Build environments](#build-environments)\n    * [Doing a build](#doing-a-build)\n+ [Syncing](#syncing)\n+ [User Interface](#user-interface)\n\n## Development\n\n### Setup your system\n\n#### MacOS\n\nPython _must_ be configured `--with-framework`. See [this StackOverflow answer](https://stackoverflow.com/a/15752676/352488) to check whether this is enabled.\n\nTo build/release you'll need to install GNU tar, which can be done with brew:\n\n```\nbrew install gnu-tar\n```\n\n#### Windows\n\nYou'll need the [Visual Studio build tools](https://visualstudio.microsoft.com/downloads/).\n\n#### Linux (Ubuntu)\n\nFor `gtk` to install properly you'll need:\n\n```\napt install build-essential pkg-config git python3-dev libcairo2-dev libgirepository1.0-dev\n```\n\n\n### Install requirements\n\n#### Python\n\nKanmail requires Python `3.9` and uses `poetry` to manage requirements, install with:\n\n```\npoetry install\n```\n\n#### JavaScript\n\nInstall the JavaScript requirements with `yarn`:\n\n```\nyarn install\n```\n\n### Start the app\n\n#### Run as a server\n\nTo start the server + webpack-server:\n\n```\nhoncho start\n```\n\nThen go to [http://localhost:4420](https://localhost:4420) to view/develop the app in a browser of your choice.\n\n\n#### Run as an app\n\nTo start the full windowed app, use:\n\n```\nhoncho start -f Procfile-app\n```\n\nNote that the webserver does not auto-reload when running in app mode.\n\n\n### Releases\n\nVersion numbers are generated at build in the date-based format: `MAJOR.YYMMDDhhmm`.\n\n## Building\n\nPer the [pyinstaller documentation](https://pyinstaller.readthedocs.io/en/stable/usage.html#platform-specific-notes), for maximum compatibility Kanmail is ideally built on the _oldest_ systems available. MacOS + Linux builds are forward, but not backward, compatible.\n\nKanmail is currently built on:\n\n+ MacOS 10.15 (using 10.10 SDK), compatible with 10.10+\n+ Ubuntu 18 64 bit, compatible with libc6 2.27+\n+ Windows 10 64 bit, compatible with ?\n\n### Build environments\n\n#### MacOS\n\nShould use the oldest SDK possible. Kanmail will be compatible with the SDK version of any newer versions, but nothing older, so target the oldest realistic SDK, which is currently 10.10 / Sierra. Heavily based on [this gist](https://gist.github.com/phfaist/a5b8a895b003822df5397731f4673042).\n\n+ Use [xcodelegacy](https://github.com/devernay/xcodelegacy) to download old OSX SDK files\n\n##### Setup a separate environment\n\n```sh\nexport BUILD_ENV_PREFIX=/opt/osx10.10-env\n\nexport PATH=\"$BUILD_ENV_PREFIX/Frameworks/Python.framework/Versions/Current/bin:$BUILD_ENV_PREFIX/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin\"\n\nexport MACOSXSDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk\n\nexport MACOSX_DEPLOYMENT_TARGET=\"10.10\"\n\nexport CFLAGS=\"-isysroot $MACOSXSDK  -I$MACOSXSDK/System/Library/Frameworks/Tk.framework/Versions/8.5/Headers -I$BUILD_ENV_PREFIX/include \"\nexport LDFLAGS=\"-isysroot $MACOSXSDK -L$BUILD_ENV_PREFIX/lib \"\nexport LD_LIBRARY_PATH=\"$BUILD_ENV_PREFIX/lib/\"\nexport CXXFLAGS=\"-isysroot $MACOSXSDK -I$BUILD_ENV_PREFIX/include \"\nexport CPPFLAGS=\"-I$MACOSXSDK/usr/include -I$BUILD_ENV_PREFIX/include -I$BUILD_ENV_PREFIX/include/openssl \"\n```\n\n##### OpenSSL\n\nDownload \u0026 untar `openssl-1.0.2u`. **On an amd64 Mac:** prefix these commands with `arch -x86_64`.\n\n```sh\n./Configure --prefix=$BUILD_ENV_PREFIX \\\n    no-hw no-hw-xxx no-ssl2 no-ssl3 no-zlib zlib-dynamic \\\n    shared enable-cms darwin64-x86_64-cc enable-ec_nistp_64_gcc_128 \\\n    -isysroot$MACOSXSDK \\\n    -mmacosx-version-min=$MACOSX_DEPLOYMENT_TARGET\nmake depend\nmake\nmake install\n```\n\n##### Python\n\nDownload \u0026 untar Python. **On an amd64 Mac:** prefix these commands with `arch -x86_64`.\n\n```sh\n./configure --prefix=$BUILD_ENV_PREFIX/ \\\n    --enable-ipv6 \\\n    --enable-framework=$BUILD_ENV_PREFIX/Frameworks/ \\\n    --with-openssl=$BUILD_ENV_PREFIX \\\n    MACOSX_DEPLOYMENT_TARGET=\"$MACOSX_DEPLOYMENT_TARGET\"\nmake\nmake install PYTHONAPPSDIR=$BUILD_ENV_PREFIX/Applications\n\n# Tidy up\ncd $BUILD_ENV_PREFIX/Frameworks/Python.framework/Versions/Current/bin\nln -s python3 python\nln -s pip3 pip\n```\n\nFinally install the requirements (from source, no binaries):\n\n```sh\npip install pip -U\npip install -r requirements/macos.txt\n```\n\nUsing this environment should now build apps compatible with MacOS 10.10+. This can be tested by [installing a MacOS 10.13 VM](https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10/).\n\n#### Linux (Ubuntu)\n\nShould use the oldest libc possible. Currently building using Ubuntu 18 which has libc6 2.27, which is pretty recent.\n\nTBC instructions to build on an older libc.\n\n#### Windows\n\nCurrently builds on Windows 10. Unsure if compatible with previous versions.\n\n### Doing a build\n\nBuilding Kanmail should be as simple as running `python -m make`.\n\n\n## Syncing\n\nKanmail syncs email using the IMAP protocol. Instead of implementing a \"complete sync engine\" (one which attempts to keep a local copy of the server data), Kanmail uses a cache and loads data on demand. This simplifies the implementation but makes it hard/impossible to behave as an offline email client.\n\nKanmail keeps in sync with the remote server by checking UID lists. These are cached locally and every \"sync\" the full list is refreshed, ensuring the local copy is up to date with the server UID list. Email headers are cached against their UIDs.\n\nCurrently no actual full email data is cached, only the headers. Meaning when offline Kanmail will load any cached threads into the column view, but it won't be able to open any of these threads.\n\n### Initial load (get emails)\n\nWhen Kanmail starts, the UI attempts to get emails for each folder (both columns and \"core\" folders like archive/drafts) - this API endpoint is always expected to return a valid response, even if empty, and does not require connectivity. If there is a local cache of UIDs and email headers, these will be returned.\n\nSubsequent calls to this API endpoint will load more emails, loading headers from the server as required.\n\n### Updates (sync emails)\n\nDuring the lifetime of a running Kanmail app it will periodically request to sync emails with the server. At this time the full UID list is reloaded from the server (failing if offline) and any new email headers are fetched. This endpoint returns new emails and the UIDs of any deleted emails from the UID list.\n\n\n## User Interface\n\nThe Kanmail UI consists of a collection of React apps, one per window \"category\".\n\n### EmailsApp\n\nThe main Kanmail window, including the column and email thread views. This is where the interesting stuff lives!\n\n#### Column / thread renders\n\nRendering columns can be expensive, so Kanmail uses a few \"hacks\" to reduce the amount of renders required. For example, when archiving or trashing a thread, it's hidden from the user but the underlying component remains in-place. Only the thread component itself updates and the surrounding column does not re-render.\n\n#### Keyboard navigation\n\nKanmail supports navigating between threads _and_ between columns using the keyboard. To achieve this every thread component contains a reference to access the component above/below (other threads same column) and also the adjacent columns left/right. This is achieved using React references.\n\n### SendApp\n\nThe send/reply/forward email window and editor.\n\n### SettingsApp\n\nThe settings window. Handles account management as well as general application settings.\n\n### ContactsApp\n\nThe contacts window. Handles add/remove/delete contacts API.\n\n### LicenseApp\n\nThe license window. Add/remove a license key.\n\n### MetaApp\n\nThe meta/about window, includes license information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOxygem%2FKanmail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOxygem%2FKanmail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOxygem%2FKanmail/lists"}