Build Python apps with Microsoft Graph

This tutorial teaches you how to build a Python console app that uses the Microsoft Graph API to access data on behalf of a user.

In this tutorial, you will:

• Get the signed-in user
• List the user's inbox messages
• Send an email

Prerequisites

Before you start this tutorial, you should have Python and pip installed on your development machine.

You should also have a Microsoft work or school account with an Exchange Online mailbox. If you don't have a Microsoft 365 tenant, you might qualify for one through the Microsoft 365 Developer Program; for details, see the FAQ. Alternatively, you can sign up for a 1-month free trial or purchase a Microsoft 365 plan.

Register the app in the portal

• 28 minutes remaining

In this exercise you will register a new application in Azure Active Directory to enable user authentication. You can register an application using the Microsoft Entra admin center, or by using the Microsoft Graph PowerShell SDK.

Register application for user authentication

In this section you will register an application that supports user authentication using device code flow.

Create a Python console app

• 25 minutes remaining

Begin by creating a new Python file.

1. Create a new file named main.py and add the following code.

   print ('Hello world!')
   

2. Save the file and use the following command to run the file.

   python3 main.py
   

   If it works, the app should output Hello world!.

Install dependencies

Before moving on, add some additional dependencies that you will use later.

• Azure Identity client library for Python to authenticate the user and acquire access tokens.
• Microsoft Graph SDK for Python (preview) to make calls to the Microsoft Graph.

Run the following commands in your CLI to install the dependencies.

python3 -m pip install azure-identity
python3 -m pip install msgraph-sdk

Load application settings

In this section you'll add the details of your app registration to the project.

1. Create a file in the same directory as main.py named config.cfg and add the following code.

   [azure]
   clientId = YOUR_CLIENT_ID_HERE
   tenantId = common
   graphUserScopes = User.Read Mail.Read Mail.Send
   

2. Update the values according to the following table.

   Setting	Value
   clientId	The client ID of your app registration
   tenantId	If you chose the option to only allow users in your organization to sign in, change this value to your tenant ID. Otherwise leave as common.

   Tip

   Optionally, you can set these values in a separate file named config.dev.cfg.

Design the app

In this section you will create a simple console-based menu.

1. Create a new file named graph.py and add the following code to that file.

   # Temporary placeholder
   class Graph:
       def __init__(self, config):
           self.settings = config
   

   This code is a placeholder. You will implement the Graph class in the next section.

2. Open main.py and replace its entire contents with the following code.

   import asyncio
   import configparser
   from msgraph.generated.models.o_data_errors.o_data_error import ODataError
   from graph import Graph
   
   async def main():
       print('Python Graph Tutorial\n')
   
       # Load settings
       config = configparser.ConfigParser()
       config.read(['config.cfg', 'config.dev.cfg'])
       azure_settings = config['azure']
   
       graph: Graph = Graph(azure_settings)
   
       await greet_user(graph)
   
       choice = -1
   
       while choice != 0:
           print('Please choose one of the following options:')
           print('0. Exit')
           print('1. Display access token')
           print('2. List my inbox')
           print('3. Send mail')
           print('4. Make a Graph call')
   
           try:
               choice = int(input())
           except ValueError:
               choice = -1
   
           try:
               if choice == 0:
                   print('Goodbye...')
               elif choice == 1:
                   await display_access_token(graph)
               elif choice == 2:
                   await list_inbox(graph)
               elif choice == 3:
                   await send_mail(graph)
               elif choice == 4:
                   await make_graph_call(graph)
               else:
                   print('Invalid choice!\n')
           except ODataError as odata_error:
               print('Error:')
               if odata_error.error:
                   print(odata_error.error.code, odata_error.error.message)
   

3. Add the following placeholder methods at the end of the file. You'll implement them in later steps.

   async def greet_user(graph: Graph):
       # TODO
       return
   
   async def display_access_token(graph: Graph):
       # TODO
       return
   
   async def list_inbox(graph: Graph):
       # TODO
       return
   
   async def send_mail(graph: Graph):
       # TODO
       return
   
   async def make_graph_call(graph: Graph):
       # TODO
       return
   

4. Add the following line to call main at the end of the file.

   # Run main
   asyncio.run(main())
   

This implements a basic menu and reads the user's choice from the command line.

Add user authentication

• 20 minutes remaining

In this section you will extend the application from the previous exercise to support authentication with Azure AD. This is required to obtain the necessary OAuth access token to call the Microsoft Graph. In this step you will integrate the Azure Identity client library for Python into the application and configure authentication for the Microsoft Graph SDK for Python (preview).

The Azure Identity library provides a number of TokenCredential classes that implement OAuth2 token flows. The Microsoft Graph SDK uses those classes to authenticate calls to Microsoft Graph.

Configure Graph client for user authentication

In this section you will use the DeviceCodeCredential class to request an access token by using the device code flow.

1. Open graph.py and replace its entire contents with the following code.

   from configparser import SectionProxy
   from azure.identity import DeviceCodeCredential
   from msgraph import GraphServiceClient
   from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder
   from msgraph.generated.users.item.mail_folders.item.messages.messages_request_builder import (
       MessagesRequestBuilder)
   from msgraph.generated.users.item.send_mail.send_mail_post_request_body import (
       SendMailPostRequestBody)
   from msgraph.generated.models.message import Message
   from msgraph.generated.models.item_body import ItemBody
   from msgraph.generated.models.body_type import BodyType
   from msgraph.generated.models.recipient import Recipient
   from msgraph.generated.models.email_address import EmailAddress
   
   class Graph:
       settings: SectionProxy
       device_code_credential: DeviceCodeCredential
       user_client: GraphServiceClient
   
       def __init__(self, config: SectionProxy):
           self.settings = config
           client_id = self.settings['clientId']
           tenant_id = self.settings['tenantId']
           graph_scopes = self.settings['graphUserScopes'].split(' ')
   
           self.device_code_credential = DeviceCodeCredential(client_id, tenant_id = tenant_id)
           self.user_client = GraphServiceClient(self.device_code_credential, graph_scopes)
   

   This code declares two private properties, a DeviceCodeCredential object and a GraphServiceClient object. The __init__ function creates a new instance of DeviceCodeCredential, then uses that instance to create a new instance of GraphServiceClient. Every time an API call is made to Microsoft Graph through the user_client, it will use the provided credential to get an access token.

2. Add the following function to graph.py.

   async def get_user_token(self):
       graph_scopes = self.settings['graphUserScopes']
       access_token = self.device_code_credential.get_token(graph_scopes)
       return access_token.token
   

3. Replace the empty display_access_token function in main.py with the following.

   async def display_access_token(graph: Graph):
       token = await graph.get_user_token()
       print('User token:', token, '\n')
   

4. Build and run the app. Enter 1 when prompted for an option. The application displays a URL and device code.

   Python Graph Tutorial
   
   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   1
   To sign in, use a web browser to open the page https://microsoft.com/devicelogin and
   enter the code RB2RUD56D to authenticate.
   

5. Open a browser and browse to the URL displayed. Enter the provided code and sign in.

   Important

   Be mindful of any existing Microsoft 365 accounts that are logged into your browser when browsing to https://microsoft.com/devicelogin. Use browser features such as profiles, guest mode, or private mode to ensure that you authenticate as the account you intend to use for testing.

6. Once completed, return to the application to see the access token.

   Tip

   For validation and debugging purposes only, you can decode user access tokens (for work or school accounts only) using Microsoft's online token parser at https://jwt.ms. This can be useful if you encounter token errors when calling Microsoft Graph. For example, verifying that the scp claim in the token contains the expected Microsoft Graph permission scopes.

Get user

• 15 minutes remaining

In this section you will incorporate the Microsoft Graph into the application. For this application, you will use the Microsoft Graph SDK for Python (preview) to make calls to Microsoft Graph.

1. Add the following function to graph.py.

   async def get_user(self):
       # Only request specific properties using $select
       query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
           select=['displayName', 'mail', 'userPrincipalName']
       )
   
       request_config = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
           query_parameters=query_params
       )
   
       user = await self.user_client.me.get(request_configuration=request_config)
       return user
   

2. Replace the empty greet_user function in main.py with the following.

   async def greet_user(graph: Graph):
       user = await graph.get_user()
       if user:
           print('Hello,', user.display_name)
           # For Work/school accounts, email is in mail property
           # Personal accounts, email is in userPrincipalName
           print('Email:', user.mail or user.user_principal_name, '\n')
   

If you run the app now, after you log in the app welcomes you by name.

Hello, Megan Bowen!
Email: [email protected]

Code explained

Consider the code in the get_user function. It's only a few lines, but there are some key details to notice.

Accessing 'me'

The function builds a request to the Get user API. This API is accessible two ways:

GET /me
GET /users/{user-id}

In this case, the code will call the GET /me API endpoint. This is a shortcut method to get the authenticated user without knowing their user ID.

Requesting specific properties

The function uses the $select query parameter to specify the set of properties it needs. Microsoft Graph will return only the requested properties in the response. In get_user, this is accomplished with the select parameter in the MeRequestBuilderGetQueryParameters object.

List inbox

• 12 minutes remaining

In this section you will add the ability to list messages in the user's email inbox.

1. Add the following function to graph.py.

   async def get_inbox(self):
       query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
           # Only request specific properties
           select=['from', 'isRead', 'receivedDateTime', 'subject'],
           # Get at most 25 results
           top=25,
           # Sort by received time, newest first
           orderby=['receivedDateTime DESC']
       )
       request_config = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
           query_parameters= query_params
       )
   
       messages = await self.user_client.me.mail_folders.by_mail_folder_id('inbox').messages.get(
               request_configuration=request_config)
       return messages
   

2. Replace the empty list_inbox function in main.py with the following.

   async def list_inbox(graph: Graph):
       message_page = await graph.get_inbox()
       if message_page and message_page.value:
           # Output each message's details
           for message in message_page.value:
               print('Message:', message.subject)
               if (
                   message.from_ and
                   message.from_.email_address
               ):
                   print('  From:', message.from_.email_address.name or 'NONE')
               else:
                   print('  From: NONE')
               print('  Status:', 'Read' if message.is_read else 'Unread')
               print('  Received:', message.received_date_time)
   
           # If @odata.nextLink is present
           more_available = message_page.odata_next_link is not None
           print('\nMore messages available?', more_available, '\n')
   

3. Run the app, sign in, and choose option 2 to list your inbox.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   2
   Message: Updates from Ask HR and other communities
     From: Contoso Demo on Yammer
     Status: Read
     Received: 2022-04-26T19:19:05Z
   Message: Employee Initiative Thoughts
     From: Patti Fernandez
     Status: Read
     Received: 2022-04-25T19:43:57Z
   Message: Voice Mail (11 seconds)
     From: Alex Wilber
     Status: Unread
     Received: 2022-04-22T19:43:23Z
   Message: Our Spring Blog Update
     From: Alex Wilber
     Status: Unread
     Received: 2022-04-19T22:19:02Z
   Message: Atlanta Flight Reservation
     From: Alex Wilber
     Status: Unread
     Received: 2022-04-19T15:15:56Z
   Message: Atlanta Trip Itinerary - down time
     From: Alex Wilber
     Status: Unread
     Received: 2022-04-18T14:24:16Z
   
   ...
   
   More messages available? True
   

Code explained

Consider the code in the get_inbox function.

Accessing well-known mail folders

The function builds a request to the List messages API. Because it includes the mail_folders.by_mail_folder_id('inbox') request builder, the API will only return messages in the requested mail folder. In this case, because the inbox is a default, well-known folder inside a user's mailbox, it's accessible via its well-known name. Non-default folders are accessed the same way, by replacing the well-known name with the mail folder's ID property. For details on the available well-known folder names, see mailFolder resource type.

Accessing a collection

Unlike the get_user function from the previous section, which returns a single object, this method returns a collection of messages. Most APIs in Microsoft Graph that return a collection do not return all available results in a single response. Instead, they use paging to return a portion of the results while providing a method for clients to request the next "page".

Default page sizes

APIs that use paging implement a default page size. For messages, the default value is 10. Clients can request more (or less) by using the $top query parameter. In get_inbox, this is accomplished with the top parameter in the MessagesRequestBuilderGetQueryParameters object.

Getting subsequent pages

If there are more results available on the server, collection responses include an @odata.nextLink property with an API URL to access the next page. The Python SDK exposes this as the odata_next_link property on collection page objects. If this property is present, there are more results available.

Sorting collections

The function uses the $orderby query parameter to request results sorted by the time the message is received (receivedDateTime property). It includes the DESC keyword so that messages received more recently are listed first. In get_inbox, this is accomplished with the orderby parameter in the MessagesRequestBuilderGetQueryParameters object.

Send mail

• 8 minutes remaining

In this section you will add the ability to send an email message as the authenticated user.

1. Add the following function to graph.py.

   async def send_mail(self, subject: str, body: str, recipient: str):
       message = Message()
       message.subject = subject
   
       message.body = ItemBody()
       message.body.content_type = BodyType.Text
       message.body.content = body
   
       to_recipient = Recipient()
       to_recipient.email_address = EmailAddress()
       to_recipient.email_address.address = recipient
       message.to_recipients = []
       message.to_recipients.append(to_recipient)
   
       request_body = SendMailPostRequestBody()
       request_body.message = message
   
       await self.user_client.me.send_mail.post(body=request_body)
   

2. Replace the empty send_mail function in main.py with the following.

   async def send_mail(graph: Graph):
       # Send mail to the signed-in user
       # Get the user for their email address
       user = await graph.get_user()
       if user:
           user_email = user.mail or user.user_principal_name
   
           await graph.send_mail('Testing Microsoft Graph', 'Hello world!', user_email or '')
           print('Mail sent.\n')
   

3. Run the app, sign in, and choose option 3 to send an email to yourself.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   3
   Mail sent.
   

   Note

   If you are testing with a developer tenant from the Microsoft 365 Developer Program, the email you send might not be delivered, and you might receive a non-delivery report. If this happens to you, please contact support via the Microsoft 365 admin center.

4. To verify the message was received, choose option 2 to list your inbox.

Code explained

Consider the code in the send_mail function.

Sending mail

The function uses the user_client.me.send_mail request builder, which builds a request to the Send mail API.

Creating objects

Unlike the previous calls to Microsoft Graph that only read data, this call creates data. To do this with the client library you create a dictionary representing the request payload, set the desired properties, then send it in the API call. Because the call is sending data, the post method is used instead of get.

Optional: add your own code

• 5 minutes remaining

In this section you will add your own Microsoft Graph capabilities to the application. This could be a code snippet from Microsoft Graph documentation or Graph Explorer, or code that you created. This section is optional.

Update the app

1. Add the following function to graph.py.

   async def make_graph_call(self):
       # INSERT YOUR CODE HERE
       return
   

2. Replace the empty make_graph_call function in main.py with the following.

   async def make_graph_call(graph: Graph):
       await graph.make_graph_call()
   

Choose an API

Find an API in Microsoft Graph you'd like to try. For example, the Create event API. You can use one of the examples in the API documentation, or create your own API request.

Configure permissions

Check the Permissions section of the reference documentation for your chosen API to see which authentication methods are supported. Some APIs don't support app-only, or personal Microsoft accounts, for example.

• To call an API with user authentication (if the API supports user (delegated) authentication), add the required permission scope in config.cfg.
• To call an API with app-only authentication see the app-only authentication tutorial.

Add your code

Copy your code into the make_graph_call function in graph.py. If you're copying a snippet from documentation or Graph Explorer, be sure to rename the GraphServiceClient to self.user_client.

Congratulations!

• 100% complete!

You've completed the Python Microsoft Graph tutorial. Now that you have a working app that calls Microsoft Graph, you can experiment and add new features.

• Learn how to use app-only authentication with the Microsoft Graph SDK for Python.
• Visit the Overview of Microsoft Graph to see all of the data you can access with Microsoft Graph.

Python samples

• Django web app
• Security API sample