Microsoft Graph Python SDK

Warnings

• breaking Major breaking changes were introduced with version 1.0.0, specifically in how authentication providers are configured and the client is instantiated. The 'GraphClient' from 'msgraph.core' was replaced by 'GraphServiceClient' from 'msgraph', and authentication moved to 'AzureIdentityAuthenticationProvider' from 'kiota_authentication_azure'.
  Fix: Review the official documentation for the latest authentication and client construction patterns. Update imports and client instantiation to use `GraphServiceClient` and `AzureIdentityAuthenticationProvider` with async credentials from `azure.identity.aio`.
• gotcha The SDK is asynchronous by default, meaning all API calls return coroutines. You must use `await` and run your code within an `asyncio` event loop or similar async framework (`anyio`, `trio`).
  Fix: Wrap your SDK calls in an `async def` function and execute it using `asyncio.run()` or integrate it into your existing asynchronous application framework.
• gotcha When sending attachments, the `content_bytes` field in attachment models (e.g., `FileAttachment`) expects raw bytes, not a base64 encoded string. The SDK handles the base64 encoding internally.
  Fix: Pass the raw byte content of the file directly to `content_bytes`. Do not manually base64 encode the content before assigning it.
• gotcha The `msgraph-sdk` package is large, and its initial installation might take a few minutes. On Windows, users might encounter `OSError` related to long paths, requiring enabling long path support.
  Fix: For Windows, enable long paths in your environment. Instructions are typically available in Microsoft documentation or by searching for 'Enable Long Paths Windows 10'.
• gotcha There are two separate SDKs: `msgraph-sdk` for the v1.0 Microsoft Graph API endpoint and `msgraph-beta-sdk` for the latest beta endpoint. Mixing them or using the wrong one can lead to unexpected behavior or missing functionalities.
  Fix: Ensure you install and import from the correct SDK (`msgraph` vs `msgraph_beta`) based on whether you intend to target the stable v1.0 API or the experimental beta API.
• gotcha The Microsoft Graph API itself can return 5xx status codes (e.g., 500 Internal Server Error, 503 Service Unavailable, 504 Gateway Timeout) which indicate server-side issues. While the SDK has a built-in retry-handler, these errors can still occur and may require application-level retry logic.
  Fix: Implement robust error handling, including retries with exponential backoff, in your application logic to gracefully handle transient 5xx errors from the Graph API. The SDK's built-in retry handler is configurable.

Install

• pip install msgraph-sdk Install stable version
• pip install msgraph-beta-sdk Install beta version (for latest APIs)

Imports

• GraphServiceClient

  from msgraph import GraphServiceClient

• AzureIdentityAuthenticationProvider

  from kiota_authentication_azure.azure_identity_authentication_provider import AzureIdentityAuthenticationProvider

  The authentication provider moved from 'msgraph.core' to 'kiota_authentication_azure' in major versions.
• ClientSecretCredential

  from azure.identity.aio import ClientSecretCredential

  The SDK is asynchronous by default, requiring async credential classes from 'azure.identity.aio'.

Quickstart

This quickstart demonstrates how to initialize the `GraphServiceClient` using `ClientSecretCredential` for app-only authentication (daemon app scenario) and fetch messages for a specific user. It highlights the asynchronous nature of the SDK and the use of environment variables for sensitive credentials. Remember to replace placeholder values and ensure your application registration has the necessary API permissions (e.g., `Mail.Read.All`) and admin consent.

import asyncio
import os
from azure.identity.aio import ClientSecretCredential
from kiota_authentication_azure.azure_identity_authentication_provider import AzureIdentityAuthenticationProvider
from msgraph import GraphServiceClient
from msgraph.generated.models.message import Message

async def main():
    # Environment variables for client credentials flow
    tenant_id = os.environ.get('TENANT_ID', 'YOUR_TENANT_ID')
    client_id = os.environ.get('CLIENT_ID', 'YOUR_CLIENT_ID')
    client_secret = os.environ.get('CLIENT_SECRET', 'YOUR_CLIENT_SECRET')
    user_id = os.environ.get('USER_ID', 'YOUR_USER_ID') # User to fetch messages from

    # Ensure required environment variables are set
    if not all([tenant_id, client_id, client_secret, user_id]):
        print("Please set TENANT_ID, CLIENT_ID, CLIENT_SECRET, and USER_ID environment variables.")
        return

    # For app-only permissions, use the .default scope
    scopes = ['https://graph.microsoft.com/.default']

    # Create a credential object
    credential = ClientSecretCredential(
        tenant_id=tenant_id,
        client_id=client_id,
        client_secret=client_secret
    )

    # Create an authentication provider
    auth_provider = AzureIdentityAuthenticationProvider(credential, scopes=scopes)

    # Create a GraphServiceClient
    client = GraphServiceClient(auth_provider)

    try:
        # Fetch messages for a specific user
        # Note: This requires Mail.Read.All application permission or Mail.Read delegated permission for the user_id
        # if using delegated flow.
        messages_collection = await client.users.by_user_id(user_id).messages.get()

        if messages_collection and messages_collection.value:
            print(f"Successfully fetched {len(messages_collection.value)} messages for user {user_id}:")
            for msg in messages_collection.value:
                print(f"  Subject: {msg.subject}, From: {msg.sender.email_address.address}")
        else:
            print(f"No messages found for user {user_id}.")

    except Exception as e:
        print(f"Error fetching messages: {e}")

if __name__ == '__main__':
    asyncio.run(main())