{"id":13877859,"url":"https://github.com/polo2ro/imapbox","last_synced_at":"2025-05-16T14:09:09.261Z","repository":{"id":27358441,"uuid":"30833778","full_name":"polo2ro/imapbox","owner":"polo2ro","description":"Dump imap inbox to a local folder in a regular backupable format: html, json and attachements","archived":false,"fork":false,"pushed_at":"2024-12-30T16:00:16.000Z","size":136,"stargazers_count":231,"open_issues_count":16,"forks_count":46,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-12T11:11:35.894Z","etag":null,"topics":["backup","imap","mailbox"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polo2ro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-02-15T16:48:29.000Z","updated_at":"2025-04-05T18:40:01.000Z","dependencies_parsed_at":"2025-04-12T09:46:24.299Z","dependency_job_id":null,"html_url":"https://github.com/polo2ro/imapbox","commit_stats":{"total_commits":103,"total_committers":18,"mean_commits":5.722222222222222,"dds":0.5631067961165048,"last_synced_commit":"04e5b9e500736fbe8e3195ae5586288d93a1fdc2"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polo2ro%2Fimapbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polo2ro%2Fimapbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polo2ro%2Fimapbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polo2ro%2Fimapbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polo2ro","download_url":"https://codeload.github.com/polo2ro/imapbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544148,"owners_count":22088808,"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":["backup","imap","mailbox"],"created_at":"2024-08-06T08:01:31.648Z","updated_at":"2025-05-16T14:09:04.253Z","avatar_url":"https://github.com/polo2ro.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"![IMAPBOX](logo.png)\n\nDump IMAP inbox to a local folder in a regular backupable format: HTML, PDF, JSON and attachments.\n\nThis program aims to save a mailbox for archive using files in indexable or searchable formats. The produced files should be readable without external software, for example, to find an email in backups using only the terminal.\n\nFor each email in an IMAP mailbox, a folder is created with the following files:\n\nFile              | Description\n------------------|------------------\n__message.html__  | If an html part exists for the message body. the `message.html` will always be in UTF-8, the embedded images links are modified to refer to the attachments subfolder.\n__message.pdf__   | This file is optionally created from `message.html` when the `wkhtmltopdf` option is set in the config file.\n__attachments__   | The attachments folder contains the attached files and the embeded images.\n__message.txt__   | This file contain the body text if available in the original email, always converted in UTF-8.\n__metadata.json__ | Various informations in JSON format, date, recipients, body text, etc... This file can be used from external applications or a search engine like [Elasticsearch](http://www.elasticsearch.com/).\n__raw.eml.gz__    | A gziped version of the email in `.eml` format.\n\nImapbox was designed to archive multiple mailboxes in one common directory tree,\ncopies of the same message spread knew several account will be archived once using the Message-Id property.\n\n## Install\n\nThis script requires Python 3.4 for `master` branch or python 2 on the `python2` branch and the following libraries:\n* [six](https://pypi.org/project/six)\n* [chardet](https://pypi.python.org/pypi/chardet) – required for character encoding detection.\n* [pdfkit](https://pypi.python.org/pypi/pdfkit) – optionally required for archiving emails to PDF.\n\nTo install the required dependencies, run:\n\n```bash\npip install -r requirements.txt\n```\n\n## Use cases\n\n* I use the script to merge all my mail accounts in one searchable directory on my NAS server.\n* Report on a website the content of an email address, like a mailing list.\n* Sharing address of several employees to perform cross-searches on a common database.\n* Archiving an IMAP account because of mailbox size restrictions, or to restrain the used disk space on the IMAP server.\n* Archiving emails to PDF format.\n\n## Config file\n\nUse `./config.cfg` `~/.config/imapbox/config.cfg` or `/etc/imapbox/config.cfg`\n\nExample:\n```ini\n[imapbox]\nlocal_folder=/var/imapbox\ndays=6\nwkhtmltopdf=/opt/bin/wkhtmltopdf\nspecific_folders=True\n\n[account1]\nhost=mail.autistici.org\nusername=username@domain\npassword=secret\nssl=True\n\n[account2]\nhost=imap.googlemail.com\nusername=username@gmail.com\npassword=secret\nremote_folder=INBOX\nport=993\n```\n\n### The imapbox section\n\nPossibles parameters for the imapbox section:\n\nParameter       | Description\n----------------|----------------------\nlocal_folder    | The full path to the folder where the emails should be stored. If the local_folder is not set, imapbox will download the emails in the current directory. This can be overwritten with the shell argument `-l`.\ndays            | Number of days back to get in the IMAP account, this should be set greater and equals to the cronjob frequency. If this parameter is not set, imapbox will get all the emails from the IMAP account. This can be overwritten with the shell argument `-d`.\nwkhtmltopdf     | (optional) The location of the `wkhtmltopdf` binary. By default `pdfkit` will attempt to locate this using `which` (on UNIX type systems) or `where` (on Windows). This can be overwritten with the shell argument `-w`.\nspecific_folders| (optional) Backup into specific account subfolders. By default all accounts will be combined into one account folder. This can be overwritten with the shell argument `-f`.\ntest_only       | (optional) Only a connection and folder retrival test will be performed. This can be overwritten with the shell argument `-t`.\n\n### Other sections\n\nYou can have has many configured account as you want, one per section. Sections names may contains the account name.\n\nPossibles parameters for an account section:\n\nParameter       | Description\n----------------|----------------------\nhost            | IMAP server hostname\nusername        | Login id for the IMAP server.\npassword        | (optional) The password will be saved in cleartext, for security reasons, you have to run the imapbox script in userspace and set `chmod 700` on your `~/.config/mailbox/config.cfg` file. The user will prompted for a password if this parameter is missing.\nremote_folder   | (optional) IMAP folder name (multiple folder name is not supported for the moment). Default value is `INBOX`. You can use `__ALL__` to fetch all folders.\nport            | (optional) Default value is `993`.\nssl             | (optional) Default value is `False`. Set to `True` to enable SSL\ndsn             | (optional) Use a specific DSN to set account paramaters. All other parameters in the account section will overwrite these. This can be used with the shell argument `-n \u003cdsn\u003e`.\n\n## Metadata file\n\nProperty        | Description\n----------------|----------------------\nSubject         | Email subject\nBody            | A text version of the message\nFrom            | Name and email of the sender\nTo              | An array of recipients\nCc              | An array of recipients\nAttachments     | An array of files names\nDate            | Message date with the timezone included, in the `RFC 2822` format\nUtc             | Message date converted in UTC, in the `ISO 8601` format. This can be used to sort emails or filter emails by date\nWithHtml        | Boolean, if the `message.html` file exists or not\nWithText        | Boolean, if the `message.txt` file exists or not\n\n## Elasticsearch\n\nThe `metadata.json` file contain the necessary informations for a search engine like [Elasticsearch](http://www.elasticsearch.com/).\nPopulate an Elasticsearch index with the emails metadata can be done with a simple script.\n\nCreate an index:\n\n```bash\ncurl -XPUT 'localhost:9200/imapbox?pretty'\n```\n\nAdd all emails to index:\n\n```bash\n#!/bin/bash\ncd emails/\nfor ID in */ ; do\n    curl -XPUT \"localhost:9200/imapbox/message/${ID}?pretty\" --data-binary \"@${ID}/metadata.json\"\ndone\n```\n\nA front-end can be used to search in email archives:\n\n* [Calaca](https://github.com/polo2ro/Calaca) is a beautiful, easy to use, search UI for Elasticsearch.\n* [Facetview](https://github.com/okfn/facetview)\n\n## Search in emails without indexation process\n\n[jq](http://stedolan.github.io/jq/) is a lightweight and flexible command-line JSON processor.\n\nExample command to browse emails:\n\n```bash\nfind . -name \"*.json\" | xargs cat | jq '[.Date, .Id, .Subject, \" ✉ \"] + .From | join(\" \")'\n```\n\nExample with a filter on UTC date:\n\n```bash\nfind . -name \"*.json\" | xargs cat | jq 'select(.Utc \u003e \"20150221T130000Z\")'\n```\n\n## Docker compose\n\n```\nversion: '3'\nservices:\n\n  imapbox:\n    image: mauricemueller/imapbox\n    container_name: imapbox\n    volumes:\n      - imapbox_data:/var/imapbox\n      # change the path to the config\n      - ./test/config.cfg:/etc/imapbox/config.cfg\n\nvolumes:\n  imapbox_data:\n```\n\n`docker-compose run --rm imapbox`\n\n## Build own docker image and push to dockerhub\n1. `docker login`\n1. `docker-compose build`\n1. `docker tag imapbox:latest [USERNAME]/imapbox:latest`\n1. `docker push [USERNAME]/imapbox:latest`\n\n\n## Similar projects\n\n[NoPriv](https://github.com/RaymiiOrg/NoPriv) is a python script to backup any IMAP capable email account to a browsable HTML archive and a Maildir folder.\n\n## License\n\nThe MIT License (MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolo2ro%2Fimapbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolo2ro%2Fimapbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolo2ro%2Fimapbox/lists"}