Metadata-Version: 2.4
Name: imapbackup3
Version: 0.3.0
Summary: A Python package for creating full backups of IMAP mailboxes
Author-email: "David M. Straub" <straub@pm.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/DavidMStraub/imapbackup3
Project-URL: Issues, https://github.com/DavidMStraub/imapbackup3/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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: Operating System :: OS Independent
Classifier: Topic :: Communications :: Email :: Post-Office :: IMAP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Dynamic: license-file

imapbackup3
===========

A Python package for creating full backups of IMAP mailboxes

## Installation

```
python3 -m pip install --user imapbackup3
```

## Command line usage

```
usage: imapbackup3 [-h] [-y] [-f FOLDERS] [-e] [-k KEY] [-c CERT] -s HOST
                   [-P PORT] -u USER [-p PASSWORD] [-m MAILBOX] [-t SECS]
                   [--thunderbird]

Back up E-mail messages from an IMAP server. mbox files are created in the
current working directory.

options:
  -h, --help            show this help message and exit
  -y, --yes-overwrite-mboxes
                        Overwite existing mbox files instead of appending
  -f, --folders FOLDERS
                        Specifify which folders use. Comma separated list.
  -e, --ssl             Use SSL. Port defaults to 993.
  -k, --key KEY         Path to PEM private key file for SSL. Specify cert,
                        too.
  -c, --cert CERT       Path to PEM certificate chain for SSL. Specify key,
                        too. Python's SSL module doesn't check the cert chain.
  -s, --server HOST     Address of server (without port)
  -P, --port PORT       Server port (defaults to 143 without and 993 with SSL)
  -u, --user USER       Username to log into server
  -p, --password PASSWORD
                        Prompts for password if not specified. If the first
                        character is '@', treat the rest as a path to a file
                        containing the password. Leading '' makes it literal.
  -m, --mailbox MAILBOX
                        Local e-mail storage format. Possible values: mbox
                        (default), Maildir
  -t, --timeout SECS    Sets socket timeout to SECS seconds.
  --thunderbird         Create Mozilla Thunderbird compatible mailbox
```

## Python usage

Minimal example (using SSL on port 993):

```python
from imapbackup3 import IMAPBackup

with IMAPBackup(host="mail.example.com", user="myuser", password="mypassword") as imb:
    imb.download_all_messages()
```

Full example:

```python
from imapbackup3 import IMAPBackup

with IMAPBackup(
    host="mail.example.com",
    user="myuser",
    password="mypassword",
    port=993,
    usessl=True,
    keyfilename="my_key.pem",
    certfilename="my_cert.pem",
    thunderbird=False,
    folders=["INBOX", "INBOX.Sent"],
    fmt="Maildir",
) as imb:
    imb.download_all_messages()
```

### Usage of the message filter

A function `msg_filter` can be passed to the `download_all_messages` method
that takes an `email.message.EmailMessage` instance as input and either
returns the same instance again (which will not change anything), returns
`None` (which will filter out the message) or returns a modified instance
(which will store the modified message). (Stupid) example:

```python
def my_filter(msg):
    if "SPAM" in msg["subject"]:
        return None
    msg["subject"] += " (no Spam)"
    return msg


imb.download_all_messages(msg_filter=my_filter)
```

## Background

This package is based on a script by [Rui Carmo](https://github.com/rcarmo/imapbackup). Original description: 

> This was first published around 2007 (probably earlier) [on my personal site][tao], and it was originally developed to work around the then rather limited (ok, inconsistent) Mac OS X Mail.app functionality and allow me to back up my old mailboxes in a fully standard `mbox` format (well, at least as much as `mbox` can be considered a standard...).

> Somewhat to my surprise it was considered useful by quite a few people throughout the years, and contributions started coming in. Given that there seems to be renewed interest in this as a systems administration tool, I'm posting the source code here and re-licensing it under the MIT license.

## Features

### Inherited from `imapbackup`

* ZERO dependencies.
* Copies every single message from every single folder (or a subset of folders) in your IMAP server to your disk.
* Does _incremental_ copying (i.e., tries very hard to not copy messages twice).
* Tries to do everything as safely as possible (only performs read operations on IMAP).
* Is completely and utterly free (distributed under the MIT license).

### New features

* Python 3 compatible, fully type-hinted
* Supports mbox or Maildir formats
* Can be imported and used as library
* When used as a library, messages can be filtered or modified on the fly

## Requirements

This package requires Python 3.10 or newer.

## Development

Clone the repository and install it in editable mode with the development
extras:

```
python3 -m pip install -e ".[dev]"
```

Run the test suite, linter, formatter and type checker:

```
pytest
ruff check .
ruff format .
mypy
```

[tao]: http://taoofmac.com/space/projects/imapbackup
