Notmuch Python Bindings

https://github.com/weilbith/notmuch-python-bindings
Admin
Python bindings for the notmuch mail search and indexing library, providing programmatic access to...
Tokens:6,745
Snippets:50
Trust Score:9.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install notmuch from Git using pip

Source: https://github.com/weilbith/notmuch-python-bindings/blob/master/README.md

Install the notmuch Python bindings directly from the Git repository using pip.

```shell
pip install from git+https://github.com/weilbith/notmuch
```

--------------------------------

### Import Notmuch Library

Source: https://github.com/weilbith/notmuch-python-bindings/blob/master/docs/source/quickstart.md

Import the notmuch library for use in your Python scripts. No specific setup is required beyond installation.

```python
import notmuch
```

--------------------------------

### Install notmuch from PyPI using pip

Source: https://github.com/weilbith/notmuch-python-bindings/blob/master/README.md

Use this command to install the notmuch Python bindings from the Python Package Index.

```shell
pip install notmuch
```

--------------------------------

### Configure Database Settings

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Manage configuration values within the notmuch database using the `Database` class. This includes getting, setting, and unsetting configuration parameters.

```python
from notmuch import Database

with Database('/home/user/mail', mode=Database.MODE.READ_WRITE) as db:
    # Get a single config value
    value = db.get_config('user.name')
    print(f"User name: {value}")

    # Set a config value
    db.set_config('user.custom_setting', 'my_value')

    # Unset a config value (set to empty string)
    db.set_config('user.custom_setting', '')

    # Get all config values with a prefix
    for key, value in db.get_configs('query.'):
        print(f"Saved query '{key[6:]}': {value}")

    # Get all config values
    for key, value in db.get_configs():
        print(f"{key} = {value}")
```

--------------------------------

### Open or Create a Notmuch Database

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Demonstrates opening existing databases in read-only or read-write modes, creating new databases, and using the context manager for safe resource handling. Also shows how to open the default database.

```python
from notmuch import Database

# Open existing database in read-only mode (default)
db = Database('/home/user/mail')
print(f"Database path: {db.get_path()}")
print(f"Database version: {db.get_version()}")

# Open in read-write mode
db_rw = Database('/home/user/mail', mode=Database.MODE.READ_WRITE)

# Create a new database
new_db = Database('/home/user/new_mail', create=True)

# Using context manager for automatic cleanup
with Database('/home/user/mail') as db:
    revision, uuid = db.get_revision()
    print(f"Database revision: {revision}, UUID: {uuid}")

    # Check if upgrade is needed
    if db.needs_upgrade():
        db.upgrade()

# Open default database from ~/.notmuch-config
db_default = Database()
```

--------------------------------

### Initialize Database and Search Messages

Source: https://github.com/weilbith/notmuch-python-bindings/blob/master/docs/source/quickstart.md

Initialize a Notmuch database and perform a search for messages from 'myself'. Ensure the database path is correct. The `create=True` argument will create the database if it does not exist.

```python
from notmuch import Query, Database

db = Database('path', create=True)
msgs = Query(db, 'from:myself').search_messages()

for msg in msgs:
    print(msg)
```

--------------------------------

### Search Messages and Threads with Query

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Illustrates how to create and configure queries to search messages and threads within a notmuch database. Shows setting sort order, excluding tags, and counting results before iterating.

```python
from notmuch import Database, Query

with Database('/home/user/mail') as db:
    # Create a query to find messages from a specific sender
    query = Query(db, 'from:alice@example.com')

    # Alternative: use Database.create_query() shorthand
    query = db.create_query('from:alice@example.com AND tag:unread')

    # Set sort order
    query.set_sort(Query.SORT.NEWEST_FIRST)
    # Other options: OLDEST_FIRST, MESSAGE_ID, UNSORTED

    # Exclude messages with certain tags
    query.exclude_tag('deleted')
    query.exclude_tag('spam')

    # Count results without iterating
    msg_count = query.count_messages()
    thread_count = query.count_threads()
    print(f"Found {msg_count} messages in {thread_count} threads")

    # Search for messages
    messages = query.search_messages()
    for msg in messages:
        print(f"Subject: {msg.get_header('subject')}")

    # Search for threads
    threads = query.search_threads()
    for thread in threads:
        print(f"Thread: {thread.get_subject()} ({thread.get_total_messages()} messages)")
```

--------------------------------

### Access Individual Email Messages

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Shows how to find and access individual email messages within a read-write database. Demonstrates retrieving message metadata, headers, filenames, tags, properties, and content parts.

```python
from notmuch import Database, Query

with Database('/home/user/mail', mode=Database.MODE.READ_WRITE) as db:
    # Find a specific message by ID
    msg = db.find_message('unique-message-id@example.com')

    # Or find by filename
    msg = db.find_message_by_filename('/home/user/mail/cur/1234567890.email')

    if msg:
        # Access message metadata
        print(f"Message ID: {msg.get_message_id()}")
        print(f"Thread ID: {msg.get_thread_id()}")
        print(f"Date: {msg.get_date()}" ) # Returns Unix timestamp
        print(f"Filename: {msg.get_filename()}")

        # Access headers (case-insensitive)
        print(f"From: {msg.get_header('From')}")
        print(f"Subject: {msg.get_header('Subject')}")
        print(f"To: {msg.get_header('To')}")

        # Get all filenames for this message
        for filename in msg.get_filenames():
            print(f"File: {filename}")

        # Get message tags
        tags = msg.get_tags()
        print(f"Tags: {' '.join(tags)}")

        # Get message properties
        prop_value = msg.get_property('session-key')
        for key, value in msg.get_properties('index.'):
            print(f"Property {key}: {value}")

        # Get message body parts
        parts = msg.get_message_parts()
        for i, part in enumerate(parts):
            print(f"Part {i}: {part.get_content_type()}")

        # Get specific part content
        body = msg.get_part(1)  # 1-indexed
```

--------------------------------

### Add notmuch to Poetry project from PyPI

Source: https://github.com/weilbith/notmuch-python-bindings/blob/master/README.md

Use this command to add the notmuch Python bindings as a dependency in a project managed by Poetry.

```shell
poetry add notmuch
```

--------------------------------

### Add notmuch to Poetry project from Git

Source: https://github.com/weilbith/notmuch-python-bindings/blob/master/README.md

Add the notmuch Python bindings as a Git dependency to a project managed by Poetry.

```shell
poetry add --git=https://github.com/weilbith/notmuch
```

--------------------------------

### Manage Message Tags with Python

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Add, remove, and atomically replace tags on messages. Optionally synchronize tags with Maildir flags. Requires a writable database connection.

```python
from notmuch import Database

with Database('/home/user/mail', mode=Database.MODE.READ_WRITE) as db:
    msg = db.find_message('message-id@example.com')

    if msg:
        # Add tags
        msg.add_tag('important')
        msg.add_tag('work', sync_maildir_flags=True)  # Sync to Maildir flags

        # Remove tags
        msg.remove_tag('unread', sync_maildir_flags=True)

        # Atomic tag replacement using freeze/thaw
        msg.freeze()
        msg.remove_all_tags(sync_maildir_flags=False)
        msg.add_tag('archive', sync_maildir_flags=False)
        msg.add_tag('processed', sync_maildir_flags=False)
        msg.thaw()
        msg.tags_to_maildir_flags()  # Sync all changes at once

        # Synchronize Maildir flags to tags
        msg.maildir_flags_to_tags()

        # Check current tags
        for tag in msg.get_tags():
            print(f"Tag: {tag}")
```

--------------------------------

### Database Operations

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Manage Notmuch databases, including opening, creating, and accessing database properties. Supports read-only and read-write modes, and context management for safe resource handling.

```APIDOC
## Database - Open or Create a Notmuch Database

### Description
The `Database` class is the highest-level object that provides access to a notmuch mail database. It can be opened in read-only or read-write mode, and supports creating new databases. The class implements the context manager protocol for safe resource management.

### Method
`Database(path=None, mode=Database.MODE.READ_ONLY, create=False)`

### Parameters
#### Path Parameters
- `path` (str) - Optional - The path to the notmuch database directory. If None, the default path from `~/.notmuch-config` is used.
- `mode` (Database.MODE) - Optional - The mode to open the database in. Defaults to `Database.MODE.READ_ONLY`. Other options include `Database.MODE.READ_WRITE`.
- `create` (bool) - Optional - If True, creates a new database at the specified path if it does not exist. Defaults to False.

### Request Example
```python
from notmuch import Database

# Open existing database in read-only mode (default)
db = Database('/home/user/mail')
print(f"Database path: {db.get_path()}")
print(f"Database version: {db.get_version()}")

# Open in read-write mode
db_rw = Database('/home/user/mail', mode=Database.MODE.READ_WRITE)

# Create a new database
new_db = Database('/home/user/new_mail', create=True)

# Using context manager for automatic cleanup
with Database('/home/user/mail') as db:
    revision, uuid = db.get_revision()
    print(f"Database revision: {revision}, UUID: {uuid}")

    # Check if upgrade is needed
    if db.needs_upgrade():
        db.upgrade()

# Open default database from ~/.notmuch-config
db_default = Database()
```

### Response
#### Success Response (200)
- `db` (Database) - An instance of the Database object.

#### Response Example
```python
# Example output from print statements in the request example
# Database path: /home/user/mail
# Database version: 4
# Database revision: 12345, UUID: abcdef123456
```
```

--------------------------------

### Status and Errors

Source: https://github.com/weilbith/notmuch-python-bindings/blob/master/docs/source/status_and_errors.md

Explains the `notmuch.STATUS` enumeration and the `NotmuchError` exception for handling operation outcomes.

```APIDOC
## Status and Errors

Some methods return a status, indicating if an operation was successful and what the error was. Most of these status codes are expressed as a specific value, the `notmuch.STATUS`.

Prior to version 0.12 the exception classes and the enumeration `notmuch.STATUS` were defined in notmuch.globals. They have since then been moved into notmuch.errors.

### `STATUS` – Notmuch operation return value

### `NotmuchError` – A Notmuch execution error

Whenever an error occurs, we throw a special Exception `NotmuchError`, or a more fine grained Exception which is derived from it. This means it is always safe to check for NotmuchErrors if you want to catch all errors. If you are interested in more fine grained exceptions, you can use those below.

The following exceptions are all directly derived from NotmuchError. Each of them corresponds to a specific `notmuch.STATUS` value. You can either check the `status` attribute of a NotmuchError to see if a specific error has occurred, or you can directly check for the following Exception types:
```

--------------------------------

### Iterate Over Database Tags

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Use the `Tags` class to iterate over tag names in the database. Note that the iterator can only be traversed once; convert to a list for multiple traversals.

```python
from notmuch import Database

with Database('/home/user/mail') as db:
    # Get all tags in the database
    all_tags = db.get_all_tags()

    # Convert to list if you need to iterate multiple times
    tag_list = list(all_tags)
    print(f"Database has {len(tag_list)} unique tags:")
    for tag in tag_list:
        print(f"  - {tag}")

    # Tags as space-separated string
    msg = db.find_message('some-id@example.com')
    if msg:
        # Note: str(tags) exhausts the iterator
        print(f"Message tags: {msg.get_tags()}")

        # For reuse, convert to list first
        tags = list(msg.get_tags())
        if 'unread' in tags:
            print("Message is unread")
```

--------------------------------

### Add and Remove Messages from Database with Python

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Index new email messages into the notmuch database or remove existing ones. Supports importing Maildir flags as tags and specifying decryption policies for encrypted content. Requires a writable database connection.

```python
from notmuch import Database, STATUS

with Database('/home/user/mail', mode=Database.MODE.READ_WRITE) as db:
    # Add a new message to the database
    msg, status = db.index_file(
        '/home/user/mail/new/1234567890.email',
        sync_maildir_flags=True  # Import Maildir flags as tags
    )

    if status == STATUS.SUCCESS:
        print(f"Added new message: {msg.get_message_id()}")
    elif status == STATUS.DUPLICATE_MESSAGE_ID:
        print(f"Message already exists, added new filename: {msg.get_message_id()}")

    # Add message with decryption policy
    msg, status = db.index_file(
        '/home/user/mail/new/encrypted.email',
        decrypt_policy=Database.DECRYPTION_POLICY.TRUE  # Try to decrypt
        # Other options: FALSE, AUTO, NOSTASH
    )

    # Remove a message
    status = db.remove_message('/home/user/mail/cur/1234567890.email')

    if status == STATUS.SUCCESS:
        print("Message completely removed from database")
    elif status == STATUS.DUPLICATE_MESSAGE_ID:
        print("Filename removed, but message still exists under other filenames")
```

--------------------------------

### Access Maildir Directories

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Utilize the `Directory` class to interact with mail directories. You can retrieve the directory path, modification time, and list child files and subdirectories.

```python
from notmuch import Database

with Database('/home/user/mail') as db:
    # Get a directory object
    directory = db.get_directory('INBOX/work')

    if directory:
        # Get directory path
        print(f"Directory path: {directory.get_path()}")

        # Get modification time
        mtime = directory.get_mtime()
        print(f"Last modified: {mtime}")

        # Set modification time (requires read-write mode)
        # directory.set_mtime(int(time.time()))

        # Get child filenames
        for filename in directory.get_child_files():
            print(f"File: {filename}")

        # Get child directories
        for subdir in directory.get_child_directories():
            print(f"Subdir: {subdir}")
```

--------------------------------

### Perform Atomic Database Operations with Python

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Group multiple database operations into a single atomic transaction. This ensures that either all operations succeed, or none of them are applied, maintaining database consistency. Requires a writable database connection.

```python
from notmuch import Database

with Database('/home/user/mail', mode=Database.MODE.READ_WRITE) as db:
    # Begin atomic section
    db.begin_atomic()

    try:
        # Perform multiple operations atomically
        msg1, _ = db.index_file('/home/user/mail/new/email1.eml')
        msg1.add_tag('processed')

        msg2, _ = db.index_file('/home/user/mail/new/email2.eml')
        msg2.add_tag('processed')

        # Changes are not visible to other processes yet

        # End atomic section - changes become visible
        db.end_atomic()

    except Exception as e:
        # If an error occurs, changes won't be committed
        print(f"Error during atomic operation: {e}")
        raise
```

--------------------------------

### Access Email Conversation Threads with Python

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Retrieve and process email conversation threads. Sort threads, access metadata like subject and authors, and iterate through messages within a thread. Requires a database connection.

```python
from notmuch import Database, Query
from datetime import datetime

with Database('/home/user/mail') as db:
    query = db.create_query('tag:inbox')
    query.set_sort(Query.SORT.NEWEST_FIRST)

    for thread in query.search_threads():
        # Thread metadata
        print(f"Thread ID: {thread.get_thread_id()}")
        print(f"Subject: {thread.get_subject()}")
        print(f"Authors: {thread.get_authors()}")

        # Message counts
        total = thread.get_total_messages()
        matched = thread.get_matched_messages()
        print(f"Messages: {matched}/{total} matched")

        # Date information
        newest = datetime.fromtimestamp(thread.get_newest_date())
        oldest = datetime.fromtimestamp(thread.get_oldest_date())
        print(f"Date range: {oldest} to {newest}")

        # Thread tags (union of all message tags)
        tags = list(thread.get_tags())
        print(f"Tags: {', '.join(tags)}")

        # Get all messages in thread
        for msg in thread.get_messages():
            print(f"  - {msg.get_header('from')}: {msg.get_header('subject')}")

        # Get only top-level messages (not replies)
        for msg in thread.get_toplevel_messages():
            # Get replies to this message
            replies = msg.get_replies()
            print(f"  Top-level: {msg.get_header('subject')} ({len(list(replies))}
 replies)")
```

--------------------------------

### Query Operations

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Perform searches within the Notmuch database using a query string. Allows setting sort order and excluding specific tags from results. Supports searching for both messages and threads.

```APIDOC
## Query - Search Messages and Threads

### Description
The `Query` class allows searching for messages and threads in the database using notmuch's powerful query syntax. Results can be sorted and filtered, and queries support excluding specific tags.

### Method
`Query(db, query_string)` or `db.create_query(query_string)`

### Parameters
#### Path Parameters
- `db` (Database) - Required - The Database object to query against.
- `query_string` (str) - Required - The notmuch query syntax string.

#### Query Parameters
(None directly on Query, but query_string uses notmuch syntax)

#### Request Body
(None for Query creation)

### Request Example
```python
from notmuch import Database, Query

with Database('/home/user/mail') as db:
    # Create a query to find messages from a specific sender
    query = Query(db, 'from:alice@example.com')

    # Alternative: use Database.create_query() shorthand
    query = db.create_query('from:alice@example.com AND tag:unread')

    # Set sort order
    query.set_sort(Query.SORT.NEWEST_FIRST)
    # Other options: OLDEST_FIRST, MESSAGE_ID, UNSORTED

    # Exclude messages with certain tags
    query.exclude_tag('deleted')
    query.exclude_tag('spam')

    # Count results without iterating
    msg_count = query.count_messages()
    thread_count = query.count_threads()
    print(f"Found {msg_count} messages in {thread_count} threads")

    # Search for messages
    messages = query.search_messages()
    for msg in messages:
        print(f"Subject: {msg.get_header('subject')}")

    # Search for threads
    threads = query.search_threads()
    for thread in threads:
        print(f"Thread: {thread.get_subject()} ({thread.get_total_messages()} messages)")
```

### Response
#### Success Response (200)
- `messages` (list[Message]) - A list of Message objects matching the query.
- `threads` (list[Thread]) - A list of Thread objects matching the query.
- `msg_count` (int) - The total number of messages matching the query.
- `thread_count` (int) - The total number of threads matching the query.

#### Response Example
```python
# Found 15 messages in 3 threads
# Subject: Meeting Reminder
# Subject: Project Update
# Thread: Project Discussion (5 messages)
```
```

--------------------------------

### Handle Notmuch Errors

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Implement robust error handling for notmuch operations using its hierarchy of exception classes, all deriving from `NotmuchError`. Specific exceptions cover read-only database issues, file errors, and more.

```python
from notmuch import (
    Database,
    NotmuchError,
    NotInitializedError,
    ReadOnlyDatabaseError,
    FileError,
    FileNotEmailError,
    DuplicateMessageIdError,
    TagTooLongError,
    XapianError,
    OutOfMemoryError,
    STATUS,
)

try:
    with Database('/home/user/mail', mode=Database.MODE.READ_WRITE) as db:
        # Attempt to add a file
        msg, status = db.index_file('/path/to/email.eml')

except ReadOnlyDatabaseError:
    print("Cannot modify: database opened in read-only mode")

except FileError as e:
    print(f"File error (not found or permission denied): {e}")

except FileNotEmailError:
    print("File does not appear to be a valid email message")

except TagTooLongError:
    print("Tag exceeds maximum length (200 bytes)")

except XapianError as e:
    print(f"Xapian database error (may need to close and reopen): {e}")

except NotInitializedError:
    print("Operation on uninitialized object")

except OutOfMemoryError:
    print("Out of memory")

except NotmuchError as e:
    # Catch-all for any notmuch error
    print(f"Notmuch error (status {e.status}): {e}")
    # Get human-readable status string
    print(f"Status message: {STATUS.status2str(e.status)}")
```

--------------------------------

### Message Operations

Source: https://context7.com/weilbith/notmuch-python-bindings/llms.txt

Access and manipulate individual email messages. Retrieve headers, content, tags, filenames, and other metadata. Supports finding messages by ID or filename.

```APIDOC
## Message - Access Individual Email Messages

### Description
The `Message` class represents a single email message and provides access to headers, content, tags, filenames, and metadata. Messages support tag manipulation with optional Maildir flag synchronization.

### Method
`db.find_message(message_id)` or `db.find_message_by_filename(filename)`

### Parameters
#### Path Parameters
- `db` (Database) - Required - The Database object to search within.
- `message_id` (str) - Required - The unique ID of the message to find.
- `filename` (str) - Required - The filesystem path to the message file.

#### Query Parameters
(None)

#### Request Body
(None for finding messages)

### Request Example
```python
from notmuch import Database, Query

with Database('/home/user/mail', mode=Database.MODE.READ_WRITE) as db:
    # Find a specific message by ID
    msg = db.find_message('unique-message-id@example.com')

    # Or find by filename
    msg = db.find_message_by_filename('/home/user/mail/cur/1234567890.email')

    if msg:
        # Access message metadata
        print(f"Message ID: {msg.get_message_id()}")
        print(f"Thread ID: {msg.get_thread_id()}")
        print(f"Date: {msg.get_date()}")  # Returns Unix timestamp
        print(f"Filename: {msg.get_filename()}")

        # Access headers (case-insensitive)
        print(f"From: {msg.get_header('From')}")
        print(f"Subject: {msg.get_header('Subject')}")
        print(f"To: {msg.get_header('To')}")

        # Get all filenames for this message
        for filename in msg.get_filenames():
            print(f"File: {filename}")

        # Get message tags
        tags = msg.get_tags()
        print(f"Tags: {' '.join(tags)}")

        # Get message properties
        prop_value = msg.get_property('session-key')
        for key, value in msg.get_properties('index.'):
            print(f"Property {key}: {value}")

        # Get message body parts
        parts = msg.get_message_parts()
        for i, part in enumerate(parts):
            print(f"Part {i}: {part.get_content_type()}")

        # Get specific part content
        body = msg.get_part(1)  # 1-indexed
```

### Response
#### Success Response (200)
- `msg` (Message) - An instance of the Message object if found.
- `messages` (list[str]) - A list of filenames associated with the message.
- `tags` (list[str]) - A list of tags applied to the message.
- `prop_value` (str) - The value of a specific property.
- `properties` (dict) - A dictionary of properties matching the prefix.
- `parts` (list[MessagePart]) - A list of MessagePart objects representing the message body.
- `body` (str) - The content of a specific message part.

#### Response Example
```python
# Message ID: unique-message-id@example.com
# Thread ID: thread-abc123
# Date: 1678886400
# Filename: /home/user/mail/cur/1234567890.email
# From: Alice <alice@example.com>
# Subject: Project Update
# To: Bob <bob@example.com>
# File: /home/user/mail/cur/1234567890.email
# Tags: inbox important
# Property index.custom: some_value
# Part 0: text/plain
# Part 1: text/html
```
```
Tokens:
Raw