Outlook Account¶

class pyOutlook.core.main.OutlookAccount(access_token: str)¶

Sets up access to an Outlook account via the Microsoft Graph API.

This is the main entry point for interacting with an Outlook account. It provides access to messages, folders, and contacts through service objects.

Parameters:

access_token (str) – OAuth token from Microsoft allowing access to a user’s account.

Variables:

access_token – The OAuth access token for API authentication.
messages (MessageService) – Service for retrieving and sending messages.
folders (FolderService) – Service for retrieving and managing mail folders.
contacts (ContactService) – Service for managing contacts and focused inbox overrides.

Example:

# Initialize with an OAuth token
account = OutlookAccount('your-access-token')

# Access inbox messages
inbox_messages = account.inbox()

# Get all folders
all_folders = account.folders.all()

# Send a message
account.messages.send(
    subject='Hello',
    body='<p>Hello World!</p>',
    to=['recipient@example.com']
)

class AutoReplyAudience¶

Constants for specifying who receives automatic replies.

Variables:

INTERNAL_ONLY – Send auto-replies only to internal organization members.
CONTACTS_ONLY – Send auto-replies only to contacts.
ALL – Send auto-replies to all senders.

ALL = 'All'¶

CONTACTS_ONLY = 'ContactsOnly'¶

INTERNAL_ONLY = 'None'¶

class AutoReplyStatus¶

Constants for automatic reply status.

Variables:

DISABLED – Auto-replies are disabled.
ALWAYS_ENABLED – Auto-replies are always sent.
SCHEDULED – Auto-replies are sent during a scheduled time window.

ALWAYS_ENABLED = 'AlwaysEnabled'¶

DISABLED = 'Disabled'¶

SCHEDULED = 'Scheduled'¶

property auto_reply_message: str¶

The account’s internal auto reply message.

Setting this property will change the auto reply message of the account, automatically enabling auto-replies (but not altering the schedule).

Returns:

The current internal auto reply message.

Return type:

str

Raises:

AuthError – If authentication fails.
RequestError – If the API request fails.

deleted_messages() → list¶

Retrieve deleted messages.

Returns the default page of messages from the Deleted Items folder (10 items per Microsoft Graph API defaults).

Returns:

Messages from the deleted items folder.

Return type:

list[Message]

Raises:

AuthError – If authentication fails.
RequestError – If the API request fails.

draft_messages() → list¶

Retrieve draft messages.

Returns the default page of messages from the Drafts folder (10 items per Microsoft Graph API defaults).

Returns:

Messages from the drafts folder.

Return type:

list[Message]

Raises:

AuthError – If authentication fails.
RequestError – If the API request fails.

inbox() → list¶

Retrieve messages from the account’s inbox.

Returns the default page of messages from the Inbox folder (10 items per Microsoft Graph API defaults).

Returns:

Messages from the inbox folder.

Return type:

list[Message]

Raises:

AuthError – If authentication fails.
RequestError – If the API request fails.

Message¶

class pyOutlook.core.message.Message(account: OutlookAccount, body: str = '', subject: str = '', to_recipients: list[Contact] | None = None, sender: Contact | None = None, cc: list[Contact] | None = None, bcc: list[Contact] | None = None, id: str | None = None, **kwargs)¶

Message model with instance methods for operations.

This class stores message data and provides instance methods for all operations that can be performed on a single message.

Parameters:

account (OutlookAccount) – The OutlookAccount instance for API authentication.
body (str) – The body content of the email, including HTML formatting.
subject (str) – The subject of the email.
to_recipients (list[Contact] or None) – List of recipients for the email.
sender (Contact or None) – The Contact who sent this email.
cc (list[Contact] or None) – List of Contacts in the CC field.
bcc (list[Contact] or None) – List of Contacts in the BCC field.
message_id (str or None) – A string provided by Outlook identifying this specific email.

Variables:

account – The associated OutlookAccount.
message_id – The Outlook message ID.
subject – The email subject.
body – The email body content with HTML formatting.
body_preview – The first 255 characters of the body.
sender (Contact) – The Contact who sent this email.
to (list[Contact]) – List of recipient Contacts.
cc (list[Contact]) – List of CC recipient Contacts.
bcc (list[Contact]) – List of BCC recipient Contacts.
is_draft – Whether the email is a draft.
is_read – Whether the email has been read.
importance – The importance level (use IMPORTANCE_LOW, IMPORTANCE_NORMAL, IMPORTANCE_HIGH).
categories (list[str]) – List of category names.
focused – Whether the message is in the focused inbox.
time_created (datetime) – When the email was created.
time_sent (datetime) – When the email was sent.
parent_folder_id – The ID of the folder containing this message.
IMPORTANCE_LOW – Low importance level (0).
IMPORTANCE_NORMAL – Normal importance level (1).
IMPORTANCE_HIGH – High importance level (2).

Example:

# Create and send a new message
message = Message(account, body='<p>Hello!</p>', subject='Greetings',
                 to_recipients=[Contact('user@example.com')])
message.send()

# Work with retrieved messages
for msg in account.inbox():
    print(msg.subject)
    msg.is_read = True  # Mark as read

IMPORTANCE_HIGH = 2¶

IMPORTANCE_LOW = 0¶

IMPORTANCE_NORMAL = 1¶

add_category(category_name: str) → None¶

Add a category to this message.

Categories are labels that can be used to organize messages. The category is added locally and, if the message has been saved, updated via the API.

Parameters:

category_name (str) – Name of the category to add.

Raises:

RequestError – If the API request fails.
AuthError – If authentication fails.

attach(file_bytes, file_name: str) → None¶

Add an attachment to this message.

The attachment is added locally for inclusion when the message is sent.

Parameters:

file_bytes (bytes or str) – The raw bytes of the file to attach, or a string that will be encoded to bytes.
file_name (str) – The filename for the attachment. Special characters will be sanitized.

property attachments: list[Attachment]¶

Get attachments, lazy-loading from API if needed.

Attachments are fetched from the API on first access and cached for subsequent calls.

Returns:: List of Attachment objects.
Return type:: list[Attachment]

copy_to(destination) → None¶

Copy this message to a destination folder.

Creates a copy of this message in the target folder.

Parameters:

destination (Folder or str) – The target folder. Can be a Folder instance, folder ID string, or well-known folder name (e.g., 'Inbox', 'DeletedItems').

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

copy_to_deleted() → None¶

Copy this message to the Deleted Items folder.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

copy_to_drafts() → None¶

Copy this message to the Drafts folder.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

copy_to_inbox() → None¶

Copy this message to the Inbox folder.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

delete() → None¶

Delete this message.

Permanently removes this message from the mailbox.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

property focused: bool¶

Get the focused status of this message.

Returns:: True if the message is in Focused inbox, False for Other.
Return type:: bool

forward(to_recipients: Contact | str | list[Contact | str], forward_comment: str | None = None) → None¶

Forward this message to recipients.

Parameters:

to_recipients (Contact or str or list[Contact] or list[str]) – Single recipient or list of recipients. Can be Contact instances or email address strings.
forward_comment (str or None) – Optional comment to include with the forwarded message.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

Example:

# Single recipient as string
message.forward('user@example.com')

# Multiple recipients as list
message.forward(['user1@example.com', 'user2@example.com'])

# With a comment
message.forward('user@example.com', forward_comment='FYI')

property headers: dict¶

HTTP headers for API requests.

Returns:: Dictionary with Authorization and Content-Type headers.
Return type:: dict

property is_read: bool¶

Get the read status of this message.

Returns:: True if the message has been read, False otherwise.
Return type:: bool

move_to(destination) → None¶

Move this message to a destination folder.

The message ID may change after moving.

Parameters:

destination (Folder or str) – The target folder. Can be a Folder instance, folder ID string, or well-known folder name (e.g., 'Inbox', 'DeletedItems').

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

move_to_deleted() → None¶

Move this message to the Deleted Items folder.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

move_to_drafts() → None¶

Move this message to the Drafts folder.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

move_to_inbox() → None¶

Move this message to the Inbox folder.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

property parent_folder: Folder¶

Returns the Folder this message is in.

Lazily loads the folder from the API using the parent_folder_id. The folder is cached after the first retrieval.

Returns:: The folder containing this message, or None if not available.
Return type:: Folder or None

Warning

This property currently calls a non-existent method and will raise an AttributeError. Use account.folders.get(message.parent_folder_id) instead until this is fixed.

reply(comment: str) → None¶

Reply to this message.

Sends a reply to the sender of this message.

Parameters:

comment (str) – The reply text. HTML formatting is supported.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

reply_all(comment: str) → None¶

Reply to all recipients of this message.

Sends a reply to the sender and all recipients (To and CC) of this message.

Parameters:

comment (str) – The reply text. HTML formatting is supported.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

send(content_type: str = 'HTML') → None¶

Sends this message.

Parameters:

content_type (str) – The content type of the body, either 'HTML' or 'Text'. Defaults to 'HTML'.

Raises:

RequestError – If the API request fails.
AuthError – If authentication fails.

Warning

This method currently uses the legacy Outlook REST API endpoint. For Microsoft Graph API support, use MessageService.send() via account.messages.send() instead.

set_focused(is_focused: bool) → None¶

Set the focused status of this message.

Moves this message to the Focused or Other section of the inbox.

Parameters:

is_focused (bool) – True for Focused inbox, False for Other.

Raises:

ValueError – If the message has no message_id.
RequestError – If the API request fails.
AuthError – If authentication fails.

set_read_status(is_read: bool) → None¶

Set the read status of this message.

If the message has a message_id, the status is updated via the API.

Parameters:

is_read (bool) – True to mark as read, False for unread.

Raises:

RequestError – If the API request fails.
AuthError – If authentication fails.

Message Service¶

class pyOutlook.services.message.MessageService(account: OutlookAccount)¶

Service class for creating Message instances from API responses.

This service acts as a factory, handling retrieval and instantiation of Message objects. All operations on individual messages are instance methods on the Message class itself.

Parameters:: account (OutlookAccount) – The OutlookAccount for API authentication.
Variables:: account – The associated OutlookAccount.

account: OutlookAccount¶

all(page: int = 0) → list[Message]¶

Retrieve multiple messages from the API.

Parameters:

page (int) – Page number for pagination (0-indexed). Each page contains 10 messages by default.

Returns:

List of messages from the specified page.

Return type:

list[Message]

Raises:

AuthError – If authentication fails.
RequestError – If the API request fails.

from_folder(folder_name: str) → list[Message]¶

Retrieve messages from a specific folder.

Parameters:

folder_name (str) – The name or ID of the folder. Well-known folder names include 'Inbox', 'SentItems', 'DeletedItems', 'Drafts'.

Returns:

List of messages from the folder.

Return type:

list[Message]

Raises:

AuthError – If authentication fails.
RequestError – If the folder is not found or the request fails.

get(message_id: str) → Message¶

Retrieve a single message from the API.

Parameters:

message_id (str) – The ID of the message to retrieve.

Returns:

The retrieved message.

Return type:

Message

Raises:

AuthError – If authentication fails.
RequestError – If the message ID is invalid or the request fails.

Send a message.

Uses the Microsoft Graph API to send a new email message.

Parameters:

subject (str) – The subject line of the message.
body (str) – The HTML body content of the message.
to (list[Contact] or list[str]) – List of recipients. Can be Contact objects or email address strings.
cc (list[Contact] or list[str] or None) – List of CC recipients. Can be Contact objects or email strings.
bcc (list[Contact] or list[str] or None) – List of BCC recipients. Can be Contact objects or email strings.
attachments (list[Attachment] or None) – List of Attachment objects to include.

Raises:

AuthError – If authentication fails.
RequestError – If the API request fails.

Example:

account.messages.send(
    subject='Meeting Tomorrow',
    body='<p>Let\'s meet at 10am.</p>',
    to=['colleague@example.com'],
    cc=[Contact('manager@example.com', name='Manager')]
)

Folder¶

class pyOutlook.core.folder.Folder(account, folder_id, folder_name, parent_id, child_folder_count, unread_count, total_items)¶

Represents a mail folder in an Outlook account.

Provides methods for managing folders and retrieving messages within them.

Parameters:

account (OutlookAccount) – The OutlookAccount this folder belongs to.
folder_id (str) – The static ID generated by Outlook to identify this folder.
folder_name (str) – The display name of this folder.
parent_id (str) – The ID of the parent folder.
child_folder_count (int) – The number of child folders inside this folder.
unread_count (int) – The number of unread messages inside this folder.
total_items (int) – Total count of all items inside this folder.

Variables:

account – The associated OutlookAccount.
id – The folder’s unique identifier.
name – The display name of the folder.
parent_id – The parent folder’s ID.
child_folder_count – Number of child folders.
unread_count – Count of unread messages.
total_items – Total items in folder.

Example:

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

# Work with a specific folder
inbox = account.folders.get('Inbox')
messages = inbox.messages()

copy_into(destination_folder: Folder) → Folder¶

Copy this folder into the destination folder.

Creates a copy of this folder as a child of the destination folder.

Parameters:

destination_folder (Folder) – The folder that should contain the copy.

Returns:

A new Folder instance representing the copied folder.

Return type:

Folder

Raises:

AuthError – If authentication fails (invalid or expired token).
RequestError – If the API request fails.

create_child_folder(folder_name: str) → Folder¶

Create a child folder within this folder.

Parameters:

folder_name (str) – The display name for the new folder.

Returns:

The newly created Folder instance.

Return type:

Folder

Raises:

AuthError – If authentication fails (invalid or expired token).
RequestError – If the API request fails.

delete() → None¶

Deletes this folder.

Permanently removes the folder and its contents from the mailbox.

Raises:

AuthError – If authentication fails (invalid or expired token).
RequestError – If the API request fails.

get_subfolders() → list[Folder]¶

Retrieve all child folders inside this folder.

Returns:

List of child Folder instances.

Return type:

list[Folder]

Raises:

AuthError – If authentication fails (invalid or expired token).
RequestError – If the API request fails.

property headers: dict¶

HTTP headers for API requests.

Returns:: Dictionary with Authorization and Content-Type headers.
Return type:: dict

messages() → list¶

Retrieve messages in this folder.

Returns the default page of messages from this folder.

Returns:

List of Message instances.

Return type:

list[Message]

Raises:

AuthError – If authentication fails (invalid or expired token).
RequestError – If the API request fails.

move_into(destination_folder: Folder) → Folder¶

Move this folder into a different folder.

This makes the current folder a child of the destination folder.

Parameters:

destination_folder (Folder) – The folder that should become the parent.

Returns:

A new Folder instance representing this folder in its new location.

Return type:

Folder

Raises:

AuthError – If authentication fails (invalid or expired token).
RequestError – If the API request fails.

rename(new_folder_name: str) → Folder¶

Renames the folder to the provided name.

Parameters:

new_folder_name (str) – The new display name for the folder.

Returns:

A new Folder instance representing the renamed folder.

Return type:

Folder

Raises:

AuthError – If authentication fails (invalid or expired token).
RequestError – If the API request fails.

Folder Service¶

class pyOutlook.services.folder.FolderService(account: OutlookAccount)¶

Service class for creating Folder instances from API responses.

This service acts as a factory, handling retrieval and instantiation of Folder objects. All operations on individual folders are instance methods on the Folder class itself.

Parameters:: account (OutlookAccount) – The OutlookAccount for API authentication.
Variables:: account – The associated OutlookAccount.

account: OutlookAccount¶

all() → list[Folder]¶

Retrieve all folders for the account.

Returns:

List of Folder instances.

Return type:

list[Folder]

Raises:

AuthError – If authentication fails.
RequestError – If the API request fails.

get(folder_id: str) → Folder¶

Retrieve a single folder by ID.

Parameters:

folder_id (str) – The ID of the folder to retrieve. Can also be a well-known folder name like 'Inbox', 'SentItems', 'DeletedItems', 'Drafts'.

Returns:

The requested Folder instance.

Return type:

Folder

Raises:

AuthError – If authentication fails.
RequestError – If the folder is not found or the request fails.

Contact¶

class pyOutlook.core.contact.Contact(email: str, name: str | None = None, focused: bool | None = None)¶

Represents someone sending or receiving an email.

Provides a structured representation of email addresses with optional name and focused inbox override settings.

Parameters:

email (str) – The email address of the contact.
name (str or None) – The contact’s display name. May be None if not provided by the API.
focused (bool or None) – Whether messages from this sender go to Focused inbox. True for Focused, False for Other, None if not set or retrieved.

Variables:

email – The email address.
name – The display name.
focused – Focused inbox override status. This value is set when retrieving a contact from the API, or after calling set_focused().

Example:

# Creating a contact for sending
recipient = Contact('user@example.com', name='John Doe')

# Using with the API
payload = dict(recipient)  # Converts to API format

set_focused(account: OutlookAccount, is_focused: bool) → bool¶

Set whether emails from this contact go to Focused or Other inbox.

Creates an inference classification override for this sender’s email address. After calling this method, all future emails from this contact will be automatically sorted to the specified inbox section.

Parameters:

account (OutlookAccount) – The OutlookAccount to set the override for.
is_focused (bool) – True to send to Focused inbox, False for Other.

Returns:

True if the request was successful.

Return type:

bool

Raises:

AuthError – If authentication fails (invalid or expired token).
RequestError – If the API request is invalid.

Contact Service¶

class pyOutlook.services.contact.ContactService(account: OutlookAccount)¶

Service class for creating Contact instances from API responses.

This service acts as a factory, handling retrieval and instantiation of Contact objects. All operations on individual contacts are instance methods on the Contact class itself.

Parameters:: account (OutlookAccount) – The OutlookAccount for API authentication.
Variables:: account – The associated OutlookAccount.

account: OutlookAccount¶

get_overrides() → list[Contact | None]¶

Retrieve contact overrides for focused inbox.

Gets the list of contacts that have focused inbox classification overrides. These are senders whose emails are always sorted to Focused or Other.

Returns:

List of Contact instances with focused status set.

Return type:

list[Contact]

Raises:

AuthError – If authentication fails.
RequestError – If the API request fails.

Attachment¶

class pyOutlook.core.attachment.Attachment(name: str, content: str, outlook_id: str | None = None, size: int | None = None, last_modified: datetime | None = None, content_type: str | None = None)¶

Represents a file attachment on an email message.

Attachments can be created for sending with new messages or retrieved from existing messages via the API.

Parameters:

name (str) – The filename of the attachment.
content (str) – The base64-encoded content of the attachment.
outlook_id (str or None) – The content ID assigned by Outlook (for retrieved attachments).
size (int or None) – The size in bytes (for retrieved attachments).
last_modified (datetime or None) – When the attachment was last modified.
content_type (str or None) – The MIME type of the attachment (e.g., 'application/pdf').

Variables:

name – The filename.
bytes (bytes) – The decoded binary content of the attachment.
outlook_id – The Outlook-assigned content ID.
size – Size in bytes.
last_modified (datetime) – Last modification timestamp.
content_type – MIME type.

Example:

# Creating an attachment for sending
import 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')

# Accessing content from a retrieved attachment
with open('downloaded.pdf', 'wb') as f:
    f.write(attachment.bytes)

api_representation() → dict¶

Returns the API-formatted dictionary representation of this attachment.

This is a convenience method that returns the same format as dict(attachment). Exists for backward compatibility with code that calls this method directly.

Returns:: Dictionary in the format expected by the Microsoft Graph API.
Return type:: dict

Example:

attachment = Attachment('file.pdf', 'base64content...')
api_format = attachment.api_representation()
# {'@odata.type': '#microsoft.graph.fileAttachment', 'name': 'file.pdf', ...}