Resources

Each API endpoint requires a resource. This usually defines the owner of the data.

Usually you will work with the default ‘ME’ resuorce, but you can also use one of the following:

  • ‘me’: the user which has given consent. the default for every protocol.

  • ‘user:user@domain.com’: a shared mailbox or a user account for which you have permissions. If you don’t provide ‘user:’ will be inferred anyways.

  • ‘sharepoint:sharepoint-site-id’: a sharepoint site id.

  • ‘group:group-site-id’: a office365 group id.

ME is the default resource used everywhere in this library. But you can change this behaviour by providing it to Protocol constructor.

This can be done however at any point (Protocol / Account / Mailbox / Message ..). Examples can be found in their respective documentation pages

Protocols

A protocol is just an interface to specify various options related to an API set, like base url, word case used for request and response attributes etc..

This project has two different set of API’s inbuilt (Office 365 APIs or Microsoft Graph APIs)

But, you can use many other Microsoft APIs as long as you implement the protocol needed.

You can use one or the other:

Choosing between Graph vs Office365 API

Reasons to use MSGraphProtocol:

  • It is the recommended Protocol by Microsoft.

  • It can access more resources over Office 365 (for example OneDrive)

Reasons to use MSOffice365Protocol:

  • It can send emails with attachments up to 150 MB. MSGraph only allows 4MB on each request.

For more details, check Graph vs Outlook API

Note

The default protocol used by the Account Class is MSGraphProtocol.

You can implement your own protocols by inheriting from Protocol to communicate with other Microsoft APIs.

Initialing Protocol

Using Graph Beta API

from O365 import MSGraphProtocol

# try the api version beta of the Microsoft Graph endpoint.
protocol = MSGraphProtocol(api_version='beta')  # MSGraphProtocol defaults to v1.0 api version

Using Shared User Account

from O365 import MSGraphProtocol

protocol = MSGraphProtocol(default_resource='shared_mailbox@example.com')

Utilizing a Protocol Instance

Protocol itself does not do anything job, it has to be plugged into this library api using Account class

from O365 import Account, MSGraphProtocol

my_protocol = MSGraphProtocol('beta', 'shared_mailbox@example.com')
account = Account(credential=('<client_id>', '<client_secret>', protocol=my_protocol))