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.
Note
To learn how to use Microsoft Graph to access data using app-only authentication, see this app-only authentication tutorial.
In this tutorial, you will:
Tip
As an alternative to following this tutorial, you can download the completed code through the quick start tool, which automates app registration and configuration. The downloaded code works without any modifications required.
You can also download or clone the GitHub repository and follow the instructions in the README to register an application and configure the project.
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.
Note
This tutorial was written with Python version 3.10.4 and pip version 20.0.2. The steps in this guide may work with other versions, but that has not been tested.
Register the app in the portal
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.
Open a browser and navigate to the Microsoft Entra admin center and login using a Global administrator account.
Select Microsoft Entra ID in the left-hand navigation, expand Identity, expand Applications, then select App registrations.
Select New registration. Enter a name for your application, for example,
Graph User Auth Tutorial
.Set Supported account types as desired. The options are:
Option Who can sign in? Accounts in this organizational directory only Only users in your Microsoft 365 organization Accounts in any organizational directory Users in any Microsoft 365 organization (work or school accounts) Accounts in any organizational directory ... and personal Microsoft accounts Users in any Microsoft 365 organization (work or school accounts) and personal Microsoft accounts Leave Redirect URI empty.
Select Register. On the application's Overview page, copy the value of the Application (client) ID and save it, you will need it in the next step. If you chose Accounts in this organizational directory only for Supported account types, also copy the Directory (tenant) ID and save it.
Select Authentication under Manage. Locate the Advanced settings section and change the Allow public client flows toggle to Yes, then choose Save.
Note
Notice that you did not configure any Microsoft Graph permissions on the app registration. This is because the sample uses dynamic consent to request specific permissions for user authentication.
Create a Python console app
Begin by creating a new Python file.
Create a new file named main.py and add the following code.
print ('Hello world!')
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.
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
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.
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.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)
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
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
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.
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 aGraphServiceClient
object. The__init__
function creates a new instance ofDeviceCodeCredential
, then uses that instance to create a new instance ofGraphServiceClient
. Every time an API call is made to Microsoft Graph through theuser_client
, it will use the provided credential to get an access token.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
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')
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.
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.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
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.
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
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: MeganB@contoso.com
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.
Note
Because the GET /me
API endpoint gets the authenticated user, it is only available to apps that use user authentication. App-only authentication apps cannot access this endpoint.
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
In this section you will add the ability to list messages in the user's email inbox.
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
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')
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.
Note
The value passed in $top
is an upper-bound, not an explicit number. The API returns a number of messages up to the specified value.
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
In this section you will add the ability to send an email message as the authenticated user.
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)
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')
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.
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
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
Add the following function to graph.py.
async def make_graph_call(self): # INSERT YOUR CODE HERE return
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!
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
Have an issue with this section? If so, please give us some feedback so we can improve this section.