zimbra-client 0.3.2__tar.gz

zimbra_client-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Chan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zimbra_client-0.3.2/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: zimbra-client
+Version: 0.3.2
+Summary: End-user Zimbra SOAP client for mail, contacts, calendar, and account settings
+Author-email: Ben Chan <kpchanaf@connect.ust.hk>
+License-Expression: MIT
+Keywords: zimbra,email,soap,mailbox,calendar,contacts
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# zimbra-client
+
+Python client for the Zimbra end-user SOAP API. Connect with an email account and work with mail, folders, drafts, contacts, calendar, tasks, signatures, preferences, and filter rules through typed methods.
+
+## Install
+
+```bash
+python -m pip install zimbra-client
+```
+
+Requires Python 3.9+. The package uses the standard library only.
+
+## Quick start
+
+```python
+from zimbra_client import ZimbraClient, ZimbraConfig
+
+config = ZimbraConfig(
+    host="https://mail.example.com",
+    email="user@example.com",
+    password="your-password",
+)
+
+with ZimbraClient(config) as client:
+    inbox = client.search_messages(folder_id="2", limit=10)
+    for summary in inbox.messages:
+        message = client.get_message(summary.id)
+        print(message.subject, message.from_.email)
+```
+
+You can also pass a mapping or keyword-style dict:
+
+```python
+client = ZimbraClient(
+    {
+        "host": "mail.example.com",
+        "email": "user@example.com",
+        "password": "your-password",
+        "verify_ssl": True,
+    }
+)
+```
+
+### Configuration options
+
+| Option | Description |
+|--------|-------------|
+| `host` | Zimbra server hostname or full `https://` URL |
+| `email` | Account email address |
+| `password` | Account password |
+| `username` | Optional login name when it differs from `email` |
+| `verify_ssl` | Validate TLS certificates (default: `False`) |
+| `timeout` | Request timeout in seconds (default: `60`) |
+
+## Mailbox
+
+```python
+with ZimbraClient(config) as client:
+    results = client.search_messages(query="from:sender@example.com", limit=25)
+
+    message = client.get_message("12345")
+    print(message.body_text, message.body_html, message.headers)
+
+    sent = client.send_message(
+        to="recipient@example.com",
+        subject="Hello",
+        text="Plain text",
+        html="<p>HTML body</p>",
+    )
+    print(sent.message_id)
+
+    client.mark_read(message.id)
+    client.move_message(message.id, folder_id="256")
+    client.trash_message(message.id)
+```
+
+Drafts, attachments, folders, tags, and other mailbox actions are available on `ZimbraClient`.
+
+## Account, contacts, calendar, and filters
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from zimbra_client import FilterRule
+from zimbra_client.filters import filter_file_into, filter_from_address, filter_stop
+
+with ZimbraClient(config) as client:
+    signatures = client.list_signatures()
+    prefs = client.get_prefs("zimbraPrefLocale")
+
+    contact = client.create_contact(
+        {"firstName": "Jane", "lastName": "Doe", "email": "jane@example.com"}
+    )
+
+    start = datetime.now(tz=timezone.utc)
+    client.create_appointment(
+        "Team sync",
+        start,
+        start + timedelta(hours=1),
+        location="Room A",
+    )
+
+    task = client.create_task("Follow up", text="Send summary")
+    client.complete_task(task.id)
+
+    client.set_filter_rules(
+        (
+            FilterRule(
+                name="Archive reports",
+                tests=(filter_from_address("reports@example.com"),),
+                actions=(filter_file_into("/Archive"), filter_stop()),
+            ),
+        )
+    )
+```
+
+## Advanced SOAP access
+
+For API calls that do not have a convenience wrapper yet, use the generic request methods:
+
+```python
+import xml.etree.ElementTree as ET
+
+from zimbra_client import ACCOUNT_NAMESPACE, ZimbraClient
+
+request = ET.Element(f"{{{ACCOUNT_NAMESPACE}}}GetInfoRequest")
+
+with ZimbraClient(config) as client:
+    response = client.request_account(request)
+```
+
+- `request_account()` sends `urn:zimbraAccount` requests
+- `request_mail()` sends `urn:zimbraMail` requests
+- `request()` is an alias that works for either namespace
+
+The client authenticates lazily, reuses the session token, retries once on session expiry, and clears credentials from error messages.
+
+## Errors
+
+The client raises typed exceptions such as `ZimbraAuthenticationError`, `ZimbraConnectionError`, `ZimbraNotFoundError`, `ZimbraLimitError`, and `ZimbraSOAPFault`.
+
+## License
+
+MIT

zimbra_client-0.3.2/README.md

@@ -0,0 +1,144 @@
+# zimbra-client
+
+Python client for the Zimbra end-user SOAP API. Connect with an email account and work with mail, folders, drafts, contacts, calendar, tasks, signatures, preferences, and filter rules through typed methods.
+
+## Install
+
+```bash
+python -m pip install zimbra-client
+```
+
+Requires Python 3.9+. The package uses the standard library only.
+
+## Quick start
+
+```python
+from zimbra_client import ZimbraClient, ZimbraConfig
+
+config = ZimbraConfig(
+    host="https://mail.example.com",
+    email="user@example.com",
+    password="your-password",
+)
+
+with ZimbraClient(config) as client:
+    inbox = client.search_messages(folder_id="2", limit=10)
+    for summary in inbox.messages:
+        message = client.get_message(summary.id)
+        print(message.subject, message.from_.email)
+```
+
+You can also pass a mapping or keyword-style dict:
+
+```python
+client = ZimbraClient(
+    {
+        "host": "mail.example.com",
+        "email": "user@example.com",
+        "password": "your-password",
+        "verify_ssl": True,
+    }
+)
+```
+
+### Configuration options
+
+| Option | Description |
+|--------|-------------|
+| `host` | Zimbra server hostname or full `https://` URL |
+| `email` | Account email address |
+| `password` | Account password |
+| `username` | Optional login name when it differs from `email` |
+| `verify_ssl` | Validate TLS certificates (default: `False`) |
+| `timeout` | Request timeout in seconds (default: `60`) |
+
+## Mailbox
+
+```python
+with ZimbraClient(config) as client:
+    results = client.search_messages(query="from:sender@example.com", limit=25)
+
+    message = client.get_message("12345")
+    print(message.body_text, message.body_html, message.headers)
+
+    sent = client.send_message(
+        to="recipient@example.com",
+        subject="Hello",
+        text="Plain text",
+        html="<p>HTML body</p>",
+    )
+    print(sent.message_id)
+
+    client.mark_read(message.id)
+    client.move_message(message.id, folder_id="256")
+    client.trash_message(message.id)
+```
+
+Drafts, attachments, folders, tags, and other mailbox actions are available on `ZimbraClient`.
+
+## Account, contacts, calendar, and filters
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from zimbra_client import FilterRule
+from zimbra_client.filters import filter_file_into, filter_from_address, filter_stop
+
+with ZimbraClient(config) as client:
+    signatures = client.list_signatures()
+    prefs = client.get_prefs("zimbraPrefLocale")
+
+    contact = client.create_contact(
+        {"firstName": "Jane", "lastName": "Doe", "email": "jane@example.com"}
+    )
+
+    start = datetime.now(tz=timezone.utc)
+    client.create_appointment(
+        "Team sync",
+        start,
+        start + timedelta(hours=1),
+        location="Room A",
+    )
+
+    task = client.create_task("Follow up", text="Send summary")
+    client.complete_task(task.id)
+
+    client.set_filter_rules(
+        (
+            FilterRule(
+                name="Archive reports",
+                tests=(filter_from_address("reports@example.com"),),
+                actions=(filter_file_into("/Archive"), filter_stop()),
+            ),
+        )
+    )
+```
+
+## Advanced SOAP access
+
+For API calls that do not have a convenience wrapper yet, use the generic request methods:
+
+```python
+import xml.etree.ElementTree as ET
+
+from zimbra_client import ACCOUNT_NAMESPACE, ZimbraClient
+
+request = ET.Element(f"{{{ACCOUNT_NAMESPACE}}}GetInfoRequest")
+
+with ZimbraClient(config) as client:
+    response = client.request_account(request)
+```
+
+- `request_account()` sends `urn:zimbraAccount` requests
+- `request_mail()` sends `urn:zimbraMail` requests
+- `request()` is an alias that works for either namespace
+
+The client authenticates lazily, reuses the session token, retries once on session expiry, and clears credentials from error messages.
+
+## Errors
+
+The client raises typed exceptions such as `ZimbraAuthenticationError`, `ZimbraConnectionError`, `ZimbraNotFoundError`, `ZimbraLimitError`, and `ZimbraSOAPFault`.
+
+## License
+
+MIT

zimbra_client-0.3.2/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zimbra-client"
+version = "0.3.2"
+description = "End-user Zimbra SOAP client for mail, contacts, calendar, and account settings"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Ben Chan", email = "kpchanaf@connect.ust.hk" },
+]
+keywords = ["zimbra", "email", "soap", "mailbox", "calendar", "contacts"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[tool.setuptools.packages.find]
+include = ["zimbra_client*"]

zimbra_client-0.3.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zimbra_client-0.3.2/tests/test_account.py

@@ -0,0 +1,99 @@
+import io
+import unittest
+import urllib.error
+import xml.etree.ElementTree as ET
+from unittest.mock import patch
+
+from zimbra_client import ZimbraClient, ZimbraConfig, local_name
+
+from tests.support.fake_zimbra import FakeZimbraDispatcher, request_name, soap_body_from_request
+
+
+class AccountTests(unittest.TestCase):
+    def setUp(self):
+        self.config = ZimbraConfig(
+            host="https://mail.example.com/",
+            email="user@example.com",
+            password="secret<&password",
+        )
+        self.client = ZimbraClient(self.config)
+        self.dispatcher = FakeZimbraDispatcher()
+
+    def test_list_and_create_signatures(self):
+        with patch("zimbra_client.client.urllib.request.urlopen", self.dispatcher):
+            signatures = self.client.list_signatures()
+            created = self.client.create_signature("Work", text="Hello & welcome")
+
+        self.assertEqual(signatures[0].name, "Default")
+        self.assertEqual(created.id, "11")
+        self.assertEqual(created.text_plain, "Hello & welcome")
+
+    def test_modify_and_delete_signature(self):
+        captured = []
+
+        def dispatch(request, timeout, context):
+            captured.append(soap_body_from_request(request))
+            return self.dispatcher(request, timeout, context)
+
+        with patch("zimbra_client.client.urllib.request.urlopen", dispatch):
+            updated = self.client.modify_signature("10", name="Updated")
+            self.client.delete_signature("10")
+
+        signature = next(elem for elem in captured[1] if local_name(elem.tag) == "signature")
+        self.assertEqual(updated.name, "Updated")
+        self.assertEqual(signature.get("id"), "10")
+
+    def test_identities_and_prefs(self):
+        with patch("zimbra_client.client.urllib.request.urlopen", self.dispatcher):
+            identities = self.client.list_identities()
+            created = self.client.create_identity(
+                "Work",
+                {"zimbraPrefFromDisplay": "Work User"},
+            )
+            modified = self.client.modify_identity("21", {"zimbraPrefFromDisplay": "Updated"})
+            self.client.delete_identity("21")
+            prefs = self.client.get_prefs("zimbraPrefLocale")
+            updated_prefs = self.client.set_prefs({"zimbraPrefLocale": "en_GB"})
+
+        self.assertEqual(identities[0].attrs["zimbraPrefFromAddress"], "user@example.com")
+        self.assertEqual(created.name, "Work")
+        self.assertEqual(modified.id, "21")
+        self.assertEqual(prefs[0].name, "zimbraPrefLocale")
+        self.assertEqual(updated_prefs[0].value, "en_GB")
+
+    def test_signature_request_xml_is_escaped(self):
+        captured = []
+
+        def dispatch(request, timeout, context):
+            captured.append(request.data)
+            return self.dispatcher(request, timeout, context)
+
+        with patch("zimbra_client.client.urllib.request.urlopen", dispatch):
+            self.client.create_signature("Sig", text="a & b")
+
+        self.assertIn(b"a &amp; b", captured[1])
+        self.assertNotIn("secret<&password", captured[1].decode("utf-8"))
+
+    def test_auth_fault_does_not_leak_password(self):
+        fault = (
+            '<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">'
+            "<soap:Body><soap:Fault>"
+            "<soap:Reason><soap:Text>failed for secret&lt;&amp;password</soap:Text></soap:Reason>"
+            '<detail><Error xmlns="urn:zimbra"><Code>account.AUTH_FAILED</Code></Error></detail>'
+            "</soap:Fault></soap:Body></soap:Envelope>"
+        ).encode("utf-8")
+        error = urllib.error.HTTPError(
+            "https://mail.example.com/service/soap",
+            500,
+            "Server Error",
+            None,
+            io.BytesIO(fault),
+        )
+        with patch("zimbra_client.client.urllib.request.urlopen", side_effect=error):
+            with self.assertRaises(Exception) as caught:
+                self.client.list_signatures()
+        self.assertNotIn("secret<&password", str(caught.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()

zimbra_client-0.3.2/tests/test_calendar.py

@@ -0,0 +1,55 @@
+import unittest
+from datetime import datetime, timezone
+from unittest.mock import patch
+
+from zimbra_client import ZimbraClient, ZimbraConfig
+
+from tests.support.fake_zimbra import FakeZimbraDispatcher
+
+
+class CalendarTests(unittest.TestCase):
+    def setUp(self):
+        self.config = ZimbraConfig(
+            host="https://mail.example.com/",
+            email="user@example.com",
+            password="secret",
+        )
+        self.client = ZimbraClient(self.config)
+        self.dispatcher = FakeZimbraDispatcher()
+        self.start = datetime(2023, 11, 14, 22, 13, 20, tzinfo=timezone.utc)
+        self.end = datetime(2023, 11, 14, 23, 13, 20, tzinfo=timezone.utc)
+
+    def test_appointment_create_list_get_cancel(self):
+        with patch("zimbra_client.client.urllib.request.urlopen", self.dispatcher):
+            created = self.client.create_appointment(
+                "Meeting",
+                self.start,
+                self.end,
+                location="Room A",
+                attendees=["guest@example.com"],
+            )
+            listed = self.client.list_appointments(self.start, self.end)
+            fetched = self.client.get_appointment("400")
+            self.client.cancel_appointment("400")
+
+        self.assertEqual(created.id, "400")
+        self.assertEqual(created.name, "Meeting")
+        self.assertEqual(listed[0].location, "Room A")
+        self.assertEqual(fetched.uid, "uid-400")
+
+    def test_task_create_get_modify_complete_list(self):
+        due = datetime(2023, 11, 16, 10, 0, tzinfo=timezone.utc)
+        with patch("zimbra_client.client.urllib.request.urlopen", self.dispatcher):
+            created = self.client.create_task("Follow up", due=due, text="Details")
+            fetched = self.client.get_task("500")
+            completed = self.client.complete_task("500")
+            tasks = self.client.list_tasks(limit=10)
+
+        self.assertEqual(created.id, "500")
+        self.assertEqual(fetched.subject, "Follow up")
+        self.assertTrue(completed.completed)
+        self.assertEqual(tasks[0].id, "501")
+
+
+if __name__ == "__main__":
+    unittest.main()