Quick Start

Instantiation

pyOutlook interacts with Outlook messages and folders through the class OutlookAccount(). The OutlookAccount acts as a gatekeeper to the other methods available, and stores the access token associated with an account.

Instantiation Example:

from pyOutlook import OutlookAccount
account_one = OutlookAccount('token 1')
account_two = OutlookAccount('token 2')

From here you can access any of the methods as documented in the pyOutlook section. Here are examples of accessing an inbox and sending a new email.

Examples

Retrieving Emails

Through the OutlookAccount class you can access the messages service, which provides methods like all(), get(), and from_folder(). The OutlookAccount also provides convenience methods like inbox(), sent_messages(), etc. These methods return a list of Message objects, allowing you to access the attributes therein.

# Get inbox messages
inbox = account.inbox()
inbox[0].body
>>> 'A very fine body'

# Get all messages (paginated)
messages = account.messages.all()
messages = account.messages.all(page=2)  # Get page 2

# Get a specific message by ID
message = account.messages.get('message_id')
print(message.subject)

# Get messages from a specific folder
drafts = account.messages.from_folder('Drafts')

Sending Emails

You can send emails through the MessageService accessed via account.messages.send(). This method takes all arguments upfront and immediately sends the email.

from pyOutlook import OutlookAccount, Contact

account = OutlookAccount('token')

# Send a simple email
account.messages.send(
    subject='Hey there',
    body="I'm sending an email through Python. <br> Best, <br> Me",
    to=['myemail@domain.com']
)

# Send with Contact objects and CC/BCC
account.messages.send(
    subject='Project Update',
    body='<p>Here is the latest update on the project.</p>',
    to=[Contact('colleague@domain.com', name='Colleague Name')],
    cc=['manager@domain.com'],
    bcc=['archive@domain.com']
)

Note that HTML formatting is accepted in the message body.

Sending with Attachments

To send attachments, create Attachment objects and pass them to the send method.

import base64
from pyOutlook import OutlookAccount, Attachment

account = OutlookAccount('token')

# Read file and encode to base64
with open('document.pdf', 'rb') as f:
    content = base64.b64encode(f.read()).decode('utf-8')

attachment = Attachment('document.pdf', content, content_type='application/pdf')

account.messages.send(
    subject='Document Attached',
    body='<p>Please find the document attached.</p>',
    to=['recipient@domain.com'],
    attachments=[attachment]
)

Contacts

All recipients, and the sender attribute, in Messages are represented by Contacts. This allows you to retrieve the name of a recipient, if provided by Outlook.

message = account.inbox()[0]
message.sender.name
>>> 'Dude'
message.sender.email
>>> 'dude@example.com'

When providing recipients to send methods, you can provide them either as a list of strings, or a list of Contacts.

from pyOutlook import Contact

# Using email strings
account.messages.send(
    subject='Hello',
    body='<p>Hi there</p>',
    to=['user1@example.com', 'user2@example.com']
)

# Using Contact objects
account.messages.send(
    subject='Hello',
    body='<p>Hi there</p>',
    to=[
        Contact('user1@example.com', name='User One'),
        Contact('user2@example.com', name='User Two')
    ]
)

Folders

You can retrieve and manage folders through the FolderService accessed via account.folders.

from pyOutlook import OutlookAccount

account = OutlookAccount('token')

# Get all folders
folders = account.folders.all()
for folder in folders:
    print(f'{folder.name}: {folder.unread_count} unread')

# Get a specific folder by ID or well-known name
inbox_folder = account.folders.get('Inbox')
custom_folder = account.folders.get('folder_id_here')

# Folder operations are methods on the Folder object
subfolder = inbox_folder.create_child_folder('Archive 2024')
inbox_folder.rename('My Inbox')