Unofficial IServ API

This Python module allows you to interact with IServ school servers using only login data for authentication. No API key is required.

Installation

pip install IServAPI

Basic usage

from IServAPI import IServAPI

# Initialize IServ instance with login credentials
api = IServAPI(username="YOUR_ISERV_USERNAME",password="YOUR_ISERV_PASSWORD", iserv_url="some_iserv_url.de")

# Example: Get the current user's information
user_info = api.get_own_user_info()

print(user_info)

Table of contents

• Unofficial IServ API
  • Installation
  • Basic usage
  • Table of contents
  • Supported Functionality

    • Own account

      • Get own User Information
      • Set own User Information
      • Fetch notifications
      • Get badges
      • Read all notifications
      • Read a specific Notification
      • Get disk space

    • Users

      • Get user avatar
      • Search users
      • Search users autocomplete
      • Get other users information

    • Email

      • Get emails
      • Get general Information about emails
      • Get email source
      • Get all mail folders
      • Send Email

    • Calendar

      • Get upcoming events
      • Get all eventsources
      • Get events
      • Search event
      • Get plugin events
      • Delete event
      • Create event

    • Misc

      • Get conference health
      • Files
      • Get folder size
      • Get groups
    • Logging
    • To-Do List
  • Contribution
  • Credits
  • License

Supported Functionality

Own account

Get own User Information

user_info = get_own_user_info()

This method retrieves information about the currently logged-in user.

Set own User Information

set_own_user_info(key=value)

This method sets your personal information

Available keys are:

title

company

birthday

nickname

_class

street

zipcode

city

country

phone

mobilePhone

fax

mail

homepage

icq

jabber

msn

skype

note

Fetch notifications

notifications = get_notifications()

Retrieves notifications from the specified URL and returns them as a JSON object.

Get badges

badges = get_badges()

Retrieves the badges from the IServ server. (Badges=numbers on sidebar)

Read all notifications

read_all_notifications()

Marks all Notification as read.

Read a specific Notification

read_notification(notification_id)

Marks a single notification as read.

Get disk space

get_disk_space()

Returns information, like free disk space, label and color about all storage volumes accessible to you. (Windows account, Cloud, etc.)

---

Users

Get user avatar

get_user_profile_picture(user, output_folder)

This method retrieves the avatar of any user on the network

It saves the avatar in the folder followed by the username,

Search users

search_users(query)

Search users autocomplete

users = search_users_autocomplete(query, limit=50)

Faster than search_users() but may not display all users

Get other users information

get_user_info(user)

Get someone else's public information this includes everything they heve set in 'Personal Information'

---

Email

Get emails

emails = get_emails(path = 'INBOX', length = 50, start = 0, order = 'date', dir = 'desc')

Retrieves emails from a specified path with optional parameters for length, start, order, and direction.

Get general Information about emails

email_info = get_email_info(path="INBOX", length=0, start=0, order="date", dir="desc")

Retrieves email information from the specified path in the mailbox. For example: unread emails.

Get email source

email_source = get_email_source(uid, path="INBOX")

Retrieves the source code of an email message from the specified email path and message ID.

Get all mail folders

mail_folders = get_mail_folders()

Retrieves the list of mail folders.

Send Email

send_email(receiver_email:str, subject:str, body:str, html_body:str=None, smtp_server:str=None, smtps_port:int=465, attachments:list=None)

Sends an email. Note all variables defaulting to none get defined later so don't worry.

sender_email must be a valid name present in the iserv network.

---

Calendar

Get upcoming events

events = get_upcoming_events()

Retrieves the upcoming events from the IServ calendar API.

Get events

events = get_events(start="2024-01-01", end="2025-12-31")

Retrieves all events of all eventsources in the specified timeframe.

---

Search for events

events = search_event(query="Party", start="2024-01-01", end="2025-12-31")

Searches for an event in the specified timeframe.

---

Get events by Plugin

events = api.get_calendar_plugin_events(
    "holiday",
    "2024.11.11",
    "2026.11.11"
)

Lists all events produced by a plugin. Plugins can be retrieved from the output of get_eventsources() where id is the plugin id if the type is plugin.

---

Get all eventsources

eventsources = get_eventsources()

Retrieves the event sources from the calendar API.

---

Delete event

status = delete_event(
  uid="XXXXXXXXXXXXXX@iservserver.de",
  _hash="541f2d74099d785d1286c03903a2e826",
  calendar="/my.iserv.account/home",
  start="2025-09-25T16:00:00+02:00",
  series=True
  )

Deletes an event. All parameters, except series, are returned by get_events().

---

Create event

create_event(
        subject = "Math exam",
        calendar: "/my.iserv.user/home",
        start: "27.09.2025 16:00",
        end: "28.09.2025 10:00",
        category: str = "exams",
        location: str = "school",
        alarms: = ["7D", "2D", "1D"],
        isAllDayLong: bool = False,
        description: str = "",
        participants: list = [],
        show_me_as: Literal["OPAQUE", "TRANSPARENT"] = "OPAQUE",
        privacy: Literal["PUBLIC", "CONFIDENTIAL", "PRIVATE"] = "PUBLIC",
        recurring: Recurring = {},
  )

Create a new event in the IServ calendar

This method constructs and submits an HTTP request to the IServ calendar API to create a new event with optional alarms, recurring patterns, and participants.

---

Parameters

• subject (str):
  The title or subject of the event.

• calendar (str):
  The ID of the calendar where the event will be created.

• start (str):
  Event start datetime in any format parsable by dateutil.parser.

• end (str):
  Event end datetime in any format parsable by dateutil.parser.

• category (str, optional):
  Category or tag for the event. Defaults to "".

• location (str, optional):
  Location of the event. Defaults to "".

• alarms (list[AlarmType], optional):
  List of alarms for the event. Each alarm can be:

  • A string: "0M", "5M", "15M", "30M", "1H", "2H", "12H", "1D", "2D", "7D"
  • A dictionary defining custom alarms:
    • Custom datetime alarm:

      alarms = [{"custom_date_time": {"dateTime": "dd.mm.YYYY HH:MM"}}]  
      

    • Custom interval alarm:

      alarms = [{  
          "custom_interval": {  
              "interval": {  
                  "days": int,  
                  "hours": int,  
                  "minutes": int,  
              },  
              "before": bool,  
          }  
      }]  
      

  Defaults to [].

• isAllDayLong (bool, optional):
  Whether the event lasts all day. Defaults to False.

• description (str, optional):
  Detailed description of the event. Defaults to "".

• participants (list, optional):
  List of participant identifiers (usernames or emails) to invite to the event. Defaults to [].

• show_me_as (Literal["OPAQUE", "TRANSPARENT"], optional):
  Visibility of the event on your calendar.

  • "OPAQUE" blocks time.
  • "TRANSPARENT" shows availability.
    Defaults to "OPAQUE".

• privacy (Literal["PUBLIC", "CONFIDENTIAL", "PRIVATE"], optional):
  Privacy level of the event. Defaults to "PUBLIC".

• recurring (Recurring, optional):
  Dictionary defining recurring event rules. Example structure:

  {  
      "intervalType": "NO|DAILY|WEEKDAYS|WEEKLY|MONTHLY|YEARLY",  
      "interval": int,           # Only for types other than NO/WEEKDAYS  
      "monthlyIntervalType": "BYMONTHDAY|BYDAY",  # Required for MONTHLY  
      "monthDayInMonth": int,    # Required if BYMONTHDAY  
      "monthInterval": str,      # Required if BYDAY  
      "monthDay": str,           # Day of week if BYDAY  
      "recurrenceDays": str,     # Comma-separated weekdays if WEEKLY  
      "endType": "NEVER|COUNT|UNTIL",  
      "endInterval": int,        # Required if COUNT  
      "untilDate": str           # Required if UNTIL, "DD.MM.YYYY"  
  }  
  

---

Notes

• All dates and times are automatically parsed and formatted to IServ's expected format.
• The method prints any error messages returned by the IServ API.

---

Misc

Get conference health

health = get_conference_health()

Get the health status of the conference API endpoint.

Files

client = file()

Possible functions:

Synchronous methods

# Checking existence of the resource

client.check("dir1/file1")
client.check("dir1")

# Get information about the resource

client.info("dir1/file1")
client.info("dir1/")

# Check free space

free_size = client.free()

# Get a list of resources

files1 = client.list()
files2 = client.list("dir1")

# Create directory

client.mkdir("dir1/dir2")

# Delete resource

client.clean("dir1/dir2")

# Copy resource

client.copy(remote_path_from="dir1/file1", remote_path_to="dir2/file1")
client.copy(remote_path_from="dir2", remote_path_to="dir3")

# Move resource

client.move(remote_path_from="dir1/file1", remote_path_to="dir2/file1")
client.move(remote_path_from="dir2", remote_path_to="dir3")

# Move resource

client.download_sync(remote_path="dir1/file1", local_path="~/Downloads/file1")
client.download_sync(remote_path="dir1/dir2/", local_path="~/Downloads/dir2/")

# Unload resource

client.upload_sync(remote_path="dir1/file1", local_path="~/Documents/file1")
client.upload_sync(remote_path="dir1/dir2/", local_path="~/Documents/dir2/")

# Publish the resource

link = client.publish("dir1/file1")
link = client.publish("dir2")

# Unpublish resource

client.unpublish("dir1/file1")
client.unpublish("dir2")

# Get the missing files

client.pull(remote_directory='dir1', local_directory='~/Documents/dir1')

# Send missing files

client.push(remote_directory='dir1', local_directory='~/Documents/dir1')

Asynchronous methods

# Load resource

kwargs = {
 'remote_path': "dir1/file1",
 'local_path':  "~/Downloads/file1",
 'callback':    callback
}
client.download_async(**kwargs)

kwargs = {
 'remote_path': "dir1/dir2/",
 'local_path':  "~/Downloads/dir2/",
 'callback':    callback
}
client.download_async(**kwargs)

# Unload resource

kwargs = {
 'remote_path': "dir1/file1",
 'local_path':  "~/Downloads/file1",
 'callback':    callback
}
client.upload_async(**kwargs)

kwargs = {
 'remote_path': "dir1/dir2/",
 'local_path':  "~/Downloads/dir2/",
 'callback':    callback
}
client.upload_async(**kwargs)

For further informations visit CloudPolis/webdav-client-python

Get folder size

get_folder_size(path)

Returns the size of a folder in human readable form.

Get groups

get_goups()

Returns a JSON object with all the group names as key and their ID as value.

---

Logging

Add this

IServAPI.setup_logging("app.log")

after your from IServAPI import IServAPI

---

To-Do List

• add search users
• more functionality
• make wiki
• Add calendar modification capabilities

---

Contribution

Contributions are welcome! If you'd like to contribute to this project, please fork the repository and submit

a pull request. Make sure to follow the existing code style and add appropriate tests for new functionality.

---

Credits

• Author @Leo-Aqua
• Author of WebDAV client Python @CloudPolis

---

License

This project is licensed under the MIT License - see the LICENSE file for details.