mailbox-org-api 0.0.1__tar.gz

mailbox_org_api-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hendrik Schlange
+
+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.

mailbox_org_api-0.0.1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.1
+Name: mailbox-org-api
+Version: 0.0.1
+Summary: A library to access the mailbox.org Business API.
+Author: Hendrik Schlange
+Author-email: Hendrik Schlange <mail@heshsum.de>
+Project-URL: Homepage, https://github.com/heshsum/mailbox-org-api
+Project-URL: Issues, https://github.com/heshsum/mailbox-org-api/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# mailbox-org-api
+A library to access the mailbox.org Business API.
+
+## Motivation and purpose 
+The goal is to provide a comprehensive library that can easily be used to integrate the business features at mailbox.org.
+
+## Installation
+### Using pip:
+```bash
+pip install mailbox-org-api
+```
+
+### Directly from source:
+```bash
+pip install git+https://github.com/heshsum/mailbox-org-api
+```
+
+## Usage
+Basic usage is fairly straightforward:
+
+```python
+from mailbox_org_api import APIClient
+
+username = 'foo'
+password = 'bar'
+
+# Initializing
+api_connection = APIClient.APIClient()
+
+# Testing with hello.world
+api_connection.hello_world()
+
+# Creating a new API session
+api_connection.auth(username, password)
+
+# Testing the session with hello.innerworld
+api_connection.hello_innerworld()
+
+# Closing the session
+api_connection.deauth()
+``` 
+
+The implemented functions follow the naming scheme of the API, but with underscores instead of points (e.g. `mail_add()` for of `mail.add`).
+
+## Here be dragons
+1. I'm not a programmer. I'm not very good at this. Be aware of my incompetence.
+2. Implementation is not complete. Not all functions of the API have been implemented
+3. Type hinting is available for most functions, but not all of them.  
+E.g. `mail_add()` accepts kwargs due to the number of available attributes. 
+In that case type errors will be returned if wrong types are provided.
+
+## API documentation
+mailbox.org provides API documentation here: [https://api.mailbox.org](https://api.mailbox.org)

mailbox_org_api-0.0.1/README.md

@@ -0,0 +1,53 @@
+# mailbox-org-api
+A library to access the mailbox.org Business API.
+
+## Motivation and purpose 
+The goal is to provide a comprehensive library that can easily be used to integrate the business features at mailbox.org.
+
+## Installation
+### Using pip:
+```bash
+pip install mailbox-org-api
+```
+
+### Directly from source:
+```bash
+pip install git+https://github.com/heshsum/mailbox-org-api
+```
+
+## Usage
+Basic usage is fairly straightforward:
+
+```python
+from mailbox_org_api import APIClient
+
+username = 'foo'
+password = 'bar'
+
+# Initializing
+api_connection = APIClient.APIClient()
+
+# Testing with hello.world
+api_connection.hello_world()
+
+# Creating a new API session
+api_connection.auth(username, password)
+
+# Testing the session with hello.innerworld
+api_connection.hello_innerworld()
+
+# Closing the session
+api_connection.deauth()
+``` 
+
+The implemented functions follow the naming scheme of the API, but with underscores instead of points (e.g. `mail_add()` for of `mail.add`).
+
+## Here be dragons
+1. I'm not a programmer. I'm not very good at this. Be aware of my incompetence.
+2. Implementation is not complete. Not all functions of the API have been implemented
+3. Type hinting is available for most functions, but not all of them.  
+E.g. `mail_add()` accepts kwargs due to the number of available attributes. 
+In that case type errors will be returned if wrong types are provided.
+
+## API documentation
+mailbox.org provides API documentation here: [https://api.mailbox.org](https://api.mailbox.org)

mailbox_org_api-0.0.1/mailbox_org_api/APIClient.py

@@ -0,0 +1,378 @@
+"""
+Module for the BMBO API client
+"""
+import json
+import requests
+
+headers = {'content-type': 'application/json'}
+domain_capabilities = ['MAIL_SPAMPROTECTION', 'MAIL_BLACKLIST', 'MAIL_BACKUPRECOVER', 'MAIL_PASSWORDRESET_SMS']
+mail_capabilities = ['MAIL_SPAMPROTECTION', 'MAIL_BLACKLIST', 'MAIL_BACKUPRECOVER', 'MAIL_OTP', 'MAIL_PASSWORDRESET_SMS']
+mail_set_arguments = {'password': str, 'password_hash': str, 'same_password_allowed': bool,
+                      'require_password_reset': bool, 'plan': str, 'additional_mail_quota': str,
+                      'additional_cloud_quota': str, 'first_name': str, 'last_name': str, 'inboxsave': bool,
+                      'forwards': list, 'aliases': list, 'alternate_mail': str, 'memo': str, 'allow_nets': str,
+                      'active': bool, 'title': str, 'birthday': str, 'position': str, 'department': str, 'company': str,
+                      'street': str, 'postal_code': str, 'city': str, 'phone': str, 'fax': str, 'cell_phone': str,
+                      'uid_extern': str, 'language': str}
+account_set_arguments = {'password': str, 'plan': str, 'memo': str, 'address_payment_first_name': str,
+                         'address_payment_last_name': str, 'address_payment_street': str,
+                         'address_payment_zipcode': str, 'address_payment_town': str, 'company': str, 'bank_iban': str,
+                         'bank_bic': str, 'bank_account_owner': str, 'av_contract_accept_name': str,
+                         'tarifflimits': list, 'av_contract_professional_secrecy': bool}
+
+class APIClient:
+    """
+    Object for API Client
+    """
+
+    def __init__(self):
+        # URL of the API
+        self.url = "https://api.mailbox.org/v1/"
+
+        # JSON RPC ID - a unique ID is required for each request during a session
+        self.jsonrpc_id = 0
+        self.level = None
+        self.auth_id = None
+
+    # Increment the request ID
+    def get_jsonrpc_id(self):
+        """Method to create the JSON RPC request ID. """
+        self.jsonrpc_id += 1
+        return str(self.jsonrpc_id)
+
+    def api_request(self, method: str, params: dict) -> dict:
+        """
+        Function to send API calls
+        :param method: the method to call
+        :param params: the parameters to send
+        :return: the response from the mailbox.org Business API
+        """
+        request = {
+            "method": method,
+            "params": params,
+            "jsonrpc": "2.0",
+            "id": self.get_jsonrpc_id()
+        }
+        print('API request:\t', request)
+
+        api_response = requests.post(
+            self.url, data=json.dumps(request), headers=headers).json()
+        print('API full response:\t', api_response)
+
+        # Depending on the type of response the return changes.
+        # If a successful result, only the result is returned
+        if 'result' in api_response:
+            print('API result:\t', api_response['result'])
+            return api_response['result']
+
+        # In case of an error, the error is returned
+        elif 'error' in api_response:
+            print(api_response['error'])
+            return api_response['error']
+
+        # If neither a success nor an error, the full response if returned
+        else:
+            return api_response
+
+    def auth(self, username, password) -> dict:
+        """
+        Function to authenticate and create a new API session
+        :param username: the username
+        :param password: the password
+        """
+        api_response = self.api_request('auth', {'user':username, 'pass':password})
+        if api_response['session']:
+            # Level gives information about the calls available
+            self.level = api_response["level"]
+            print('Level:', self.level)
+
+            # The session id
+            self.auth_id = str(api_response["session"])
+            print('Auth ID:', self.auth_id)
+            # The auth-header is added to the list of headers, as it has to be provided with each call
+            headers.update({"HPLS-AUTH": self.auth_id})
+        return api_response
+
+    def deauth(self) -> dict:
+        """
+        Function to close the current API session
+        :return: True if the API session is closed, False otherwise
+        """
+        api_response = self.api_request('deauth',{})
+        if api_response:
+            # The auth header is stripped
+            del headers["HPLS-AUTH"]
+        return api_response
+
+    def hello_world(self):
+        """
+        Function for hello world, just to test the connection
+        :return: The response from the mailbox.org Business API
+        """
+        api_response = self.api_request('hello.world',{})
+        return api_response
+
+    def hello_innerworld(self):
+        """
+        Hello World function to test the authentication
+        :return: The response from the mailbox.org Business API
+        """
+        api_response = self.api_request('hello.innerworld', {})
+        return api_response
+
+    def account_add(self, account_name: str) -> dict:
+        """
+        Function to create a new account
+        :param account_name: the account name to create
+        :return: the response from the mailbox.org Business API
+        """
+        api_response = self.api_request('account.add', {'account_name':account_name})
+        return api_response
+
+    def account_get(self, account_name: str) -> dict:
+        """
+        Function to get a specific account
+        :param account_name: the account name to get
+        :return: the response from the mailbox.org Business API
+        """
+        api_response = self.api_request('account.get', {'account_name':account_name})
+        return api_response
+
+    def account_set(self, account_name: str, attributes: dict) -> dict:
+        """
+        Function to update a specific account
+        :param account_name: the account name to update
+        :param attributes: the attributes to update
+        :return: the response from the mailbox.org Business API
+        """
+        params = {'account':account_name}
+        for attribute in attributes:
+            print('Attribute:', attribute)
+            if attribute not in account_set_arguments:
+                raise ValueError(attribute, 'not found')
+            if type(attributes[attribute]) != account_set_arguments[attribute]:
+                errormsg = ('Attribute ' + attribute + ' must be of type ' + str(account_set_arguments[attribute]) + '. '
+                            + str(type(attributes[attribute])) + ' provided.')
+                raise TypeError(errormsg)
+            params.update({attribute: attributes[attribute]})
+        api_response = self.api_request('account.set', params)
+        return api_response
+
+    def account_del(self, account_name: str) -> dict:
+        """
+        Function to delete a specific account
+        :param account_name: the account name to delete
+        :return: the response from the mailbox.org Business API
+        """
+        api_response = self.api_request('account.del', {'account_name':account_name})
+        return api_response
+
+    def domain_list(self, account: str) -> dict:
+        """
+        Function to list all domains
+        :param account: the account to list domains for
+        :return: the API response
+        """
+        api_response = self.api_request('domain.list',{'account':account})
+        return api_response
+
+    def domain_add(self, account: str, domain: str, password: str) -> dict:
+        """
+        Function to add a domain
+        :param account: the account to add a domain for
+        :param domain: the domain to add
+        :param password: the password of the domain
+        :return: the API response
+        """
+        api_response = self.api_request('domain.add', {'account':account, 'domain':domain, 'password':password})
+        return api_response
+
+    def domain_get(self, domain: str) -> dict:
+        """
+        Function to get a specific domain
+        :param domain: the domain to get
+        :return: the API response
+        """
+        api_response = self.api_request('domain.get',{'domain':domain})
+        return api_response
+
+    def domain_capabilities_set(self, domain: str, capabilties: dict) -> dict:
+        """
+        Function to set a domain capabilities
+        :param domain: the domain to set the capabilities for
+        :param capabilties: a list of capabilities to set for the domain
+        :return: the API response
+        """
+        params = {'domain': domain}
+        for element in capabilties:
+            if element not in domain_capabilities:
+                break
+            params.update({element: capabilties[element]})
+        api_response = self.api_request('domain.capabilities.set', params)
+        return api_response
+
+    def domain_set(self, domain: str, attributes: dict) -> dict:
+        """
+        Function to set a domain
+        :param domain: the domain to update
+        :param attributes: the attributes to set
+        :return:
+        """
+        params = {'domain':domain }
+        for element in attributes:
+            params.update({element:attributes[element]})
+
+        api_response = self.api_request('domain.set', params)
+        return api_response
+
+    def domain_del(self, account: str, domain: str) -> dict:
+        """
+        Function to delete a domain
+        :param account: the account to delete a domain in
+        :param domain: the domain to delete
+        :return: the API response
+        """
+        api_response = self.api_request('domain.del', {'account':account, 'domain':domain})
+        return api_response
+
+    def mail_list(self, domain) -> dict:
+        """
+        Function to list all mailboxes
+        :return: the response from the mailbox.org Business API
+        """
+        api_response = self.api_request('mail.list', {'domain':domain})
+        return api_response
+
+    def mail_add(self, mail:str, password: str, plan: str, first_name: str, last_name: str, inboxsave: bool = True,
+                 forwards: list = None, memo: str = None, language: str = 'en_EN', uid_extern: str = None) -> dict:
+        """
+        Function to add a mail
+        :param mail: the mail to add
+        :param password: the password for the mail
+        :param plan: the plan of the mail
+        :param first_name: the first name of the mail
+        :param last_name: the last name of the mail
+        :param inboxsave: True if the mail should be saved into the inbox folder (relevant for forwards)
+        :param forwards: List of addresses to forwards mails to
+        :param memo: Memo of the mail
+        :param language: the language of the mail in locale format
+        :param uid_extern: the external UID of the mail
+        :return: the response for the request
+        """
+        if forwards is None:
+            forwards = []
+        if memo is None:
+            memo = ''
+        api_response = self.api_request('mail.add',{'mail':mail, 'password':password, 'plan':plan,
+                                                    'first_name':first_name, 'last_name':last_name,
+                                                    'inboxsave':inboxsave, 'forwards':forwards, 'memo':memo,
+                                                    'language':language, 'uid_extern':uid_extern})
+        return api_response
+
+    def mail_get(self, mail: str):
+        """
+        Function to retrieve a mail address
+        :param mail: the mail to retrieve
+        :return the response for the request
+        """
+        api_response = self.api_request('mail.get', {'mail':mail})
+        return api_response
+
+    def mail_set(self, mail: str, attributes: dict):
+        """
+        Function to update a mail
+        :param mail: the mail to update
+        :param attributes: dict of the attributes to update
+        :return:
+        """
+        params = {'mail':mail}
+        for attribute in attributes:
+            print('Attribute:', attribute)
+            if attribute not in mail_set_arguments:
+                raise ValueError(attribute, 'not found')
+            if type(attributes[attribute]) != mail_set_arguments[attribute]:
+                errormsg = ('Attribute ' + attribute + ' must be of type ' + str(mail_set_arguments[attribute]) + '. '
+                            + str(type(attributes[attribute])) + ' provided.')
+                raise TypeError(errormsg)
+            params.update({attribute: attributes[attribute]})
+        api_response = self.api_request('mail.set', params)
+        return api_response
+
+    def mail_capabilities_set(self, mail: str, capabilties: dict) -> dict:
+        """
+        Function to set a domain capabilities
+        :param mail: the mail to set the capabilities for
+        :param capabilties: a list of capabilities to set for the domain
+        :return: the API response
+        """
+        params = {'mail': mail}
+        for attribute in capabilties:
+            if attribute not in mail_capabilities:
+                raise ValueError(attribute, 'not found')
+            params.update({attribute: capabilties[attribute]})
+        api_response = self.api_request('mail.capabilities.set', params)
+        return api_response
+
+    def mail_del(self, mail: str) -> dict:
+        """
+        Function to delete a mail
+        :param mail: the mail to delete
+        :return: the response for the request
+        """
+        api_response = self.api_request('mail.del', {'mail':mail})
+        return api_response
+
+    def mail_apppassword_list(self, mail:str) -> dict:
+        """
+        Function to list all app passwords of a given mail
+        :param mail: the mail to list app passwords for
+        :return: the response for the request
+        """
+        api_response = self.api_request('mail.apppassword.list', {'mail':mail})
+        return api_response
+
+    def mail_apppassword_add(self, mail:str, memo:str) -> dict:
+        """
+        Function to generate a new mail app password for a mail
+        :param mail: the mail to generate a new mail app password
+        :param memo: memo of the app password
+        :return: the response for the request
+        """
+        api_response = self.api_request('mail.apppassword.add', {'mail':mail, 'memo':memo})
+        return api_response
+
+    def mail_apppassword_delete(self, apppassword_id: int) -> dict:
+        """
+        Function to delete a mail app password
+        :param apppassword_id: the id of the mail app password
+        :return: the response for the request
+        """
+        api_response = self.api_request('mail.apppassword.delete', {'id':apppassword_id})
+        return api_response
+
+    def mail_externaluid(self, mail: str) -> dict:
+        """
+        Function to get a mail using an external UID
+        :param mail: the mail to get
+        :return: the response for the request
+        """
+        api_response = self.api_request('mail.externaluid', {'mail':mail})
+        return api_response
+
+    def context_list(self, account: str) -> dict:
+        """
+        Function to list all contexts of a given account
+        :param account: the account to list all contexts for
+        :return: the response for the request
+        """
+        api_response = self.api_request('context.list', {'account':account})
+        return api_response
+
+    def search(self, search_string: str) -> dict:
+        """
+        Function to search for accounts, domains and email addresses
+        :param search_string: the query to search by
+        :return: the response for the request
+        """
+        api_response = self.api_request('search', {'search':search_string})
+        return api_response

mailbox_org_api-0.0.1/mailbox_org_api.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.1
+Name: mailbox-org-api
+Version: 0.0.1
+Summary: A library to access the mailbox.org Business API.
+Author: Hendrik Schlange
+Author-email: Hendrik Schlange <mail@heshsum.de>
+Project-URL: Homepage, https://github.com/heshsum/mailbox-org-api
+Project-URL: Issues, https://github.com/heshsum/mailbox-org-api/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# mailbox-org-api
+A library to access the mailbox.org Business API.
+
+## Motivation and purpose 
+The goal is to provide a comprehensive library that can easily be used to integrate the business features at mailbox.org.
+
+## Installation
+### Using pip:
+```bash
+pip install mailbox-org-api
+```
+
+### Directly from source:
+```bash
+pip install git+https://github.com/heshsum/mailbox-org-api
+```
+
+## Usage
+Basic usage is fairly straightforward:
+
+```python
+from mailbox_org_api import APIClient
+
+username = 'foo'
+password = 'bar'
+
+# Initializing
+api_connection = APIClient.APIClient()
+
+# Testing with hello.world
+api_connection.hello_world()
+
+# Creating a new API session
+api_connection.auth(username, password)
+
+# Testing the session with hello.innerworld
+api_connection.hello_innerworld()
+
+# Closing the session
+api_connection.deauth()
+``` 
+
+The implemented functions follow the naming scheme of the API, but with underscores instead of points (e.g. `mail_add()` for of `mail.add`).
+
+## Here be dragons
+1. I'm not a programmer. I'm not very good at this. Be aware of my incompetence.
+2. Implementation is not complete. Not all functions of the API have been implemented
+3. Type hinting is available for most functions, but not all of them.  
+E.g. `mail_add()` accepts kwargs due to the number of available attributes. 
+In that case type errors will be returned if wrong types are provided.
+
+## API documentation
+mailbox.org provides API documentation here: [https://api.mailbox.org](https://api.mailbox.org)

mailbox_org_api-0.0.1/mailbox_org_api.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+mailbox_org_api/APIClient.py
+mailbox_org_api/__init__.py
+mailbox_org_api.egg-info/PKG-INFO
+mailbox_org_api.egg-info/SOURCES.txt
+mailbox_org_api.egg-info/dependency_links.txt
+mailbox_org_api.egg-info/top_level.txt
+tests/__init__.py
+tests/tests.py

mailbox_org_api-0.0.1/mailbox_org_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mailbox_org_api-0.0.1/mailbox_org_api.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+mailbox_org_api
+tests

mailbox_org_api-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "mailbox-org-api"
+version = "0.0.1"
+authors = [
+  { name="Hendrik Schlange", email="mail@heshsum.de" },
+]
+description = "A library to access the mailbox.org Business API."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/heshsum/mailbox-org-api"
+Issues = "https://github.com/heshsum/mailbox-org-api/issues"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

mailbox_org_api-0.0.1/setup.cfg

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

mailbox_org_api-0.0.1/setup.py

@@ -0,0 +1,12 @@
+from setuptools import find_packages, setup
+
+setup(
+    name='mailbox_org_api',
+    packages=find_packages(),
+    version='0.0.1',
+    description='A library to access the mailbox.org Business API',
+    author='Hendrik Schlange',
+    install_requires=['requests'],
+    tests_require=['pytest'],
+    test_suite='tests',
+)

mailbox_org_api-0.0.1/tests/tests.py

@@ -0,0 +1,14 @@
+import pytest
+from mailbox_org_api import APIClient
+
+def test_headers():
+    client = APIClient.APIClient()
+    assert client.auth_id is None
+    assert client.level is None
+    assert client.jsonrpc_id == 0
+
+def test_hello_world():
+    client = APIClient.APIClient()
+    assert client.jsonrpc_id == 0
+    assert client.hello_world() == 'Hello World!'
+    assert client.jsonrpc_id == 1