2. Getting started¶

2.1. Connecting to a server¶

To be able to do anything, of course we first need to connect to a Kopano server. For non-interactive use, we recommend to do this as follows:

import kopano

server = kopano.server()

Note that for Kopano Core 8.7 and older, one needs to use kopano.Server() instead.

If the Kopano server is not in a default location, we can specify how to connect to it as follows:

import kopano

server = kopano.server(
    server_socket='<https://remoteip:237/kopano>',
    sslkey_file='</etc/kopano/ssl/server.pem>',
    sslkey_pass='<password>'
)

Python-kopano will first look at the provided arguments to determine how and where to connect. If there are no such arguments, it will try to get useful settings from /etc/kopano/admin.cfg. If this also doesn’t exist, it will fall-back to the default UNIX socket.

2.2. Accessing stores¶

Now that we are connected to a Kopano server, let us access a certain user store.

store = server.user('<username>').store

One can also use the following shortcut, so that an explicit server object is not needed.

store = kopano.user('<username>').store

In general, the kopano module can like a server object. However, we recommend to only use this functionality in interactive mode (that is, from a Python shell), to save on typing.

2.3. Accessing folders¶

A folder can be opened from a store using a folder name (or path):

inbox = store.folder('Inbox')
other_folder = store.folder('Inbox/some_subfolder')

For special folders, there exist special shortcuts:

inbox = store.inbox
junk = store.junk

To know the number of items in a folder:

count = inbox.count

Note that it is usually not needed to use an explicit store object. If there’s no ambiguity, we can directly use the user object:

inbox = user.inbox

2.4. Looping over items and their properties¶

Let’s loop over all items in a certain folder:

for item in user.junk:
    print(item.received, item.subject)

A MAPI item is basically just a collection of MAPI properties. Here’s how to loop over them:

for prop in item:
    print(prop, prop.value)

Let’s access a specific property, which holds the subject of the respective item:

from MAPI.Tags import PR_SUBJECT_W # python-mapi
print(item.prop(PR_SUBJECT_W).value)

Or to avoid the MAPI import:

print(item.prop('PR_SUBJECT_W').value)

So-called named properties can be accessed as follows:

PidLidReminderSignalTime = "PT_SYSTIME:common:0x8560"
print(item.prop(PidLidReminderSignalTime).value)

2.5. Accessing items¶

An item (which can be a mail, appointment, contact..) can be opened by entryid:

item = store.item(entryid)

Where the entryid comes from a log-file, for example, or is previously determined:

entryid = item.entryid

Item attributes can be changed as follows:

if 'cheese' in item.subject:
    item.subject = item.subject.upper()

2.6. Sending an email¶

Attributes can also be passed when creating an item. Using this we can create and send a simple email:

item = user.outbox.create_item(
    to='john@doe.com',
    subject='test email',
    body='Hi john!')
item.send()

2.7. Where to go from here¶

After going through these basic examples, we hope our Reference Guide can help you further. Please do let us know if something remains unclear and/or not sufficiently documented.

For real-life examples, you may also want to look at Kopano Core (related) components written using Python-Kopano, for example: