{"id":2140,"library":"o365","title":"O365 - Microsoft Graph and Office 365 API made easy","description":"The `o365` Python library provides a simple and Pythonic interface for interacting with Microsoft Graph and Office 365 APIs. It supports access to various services including Email, Calendar, Contacts, OneDrive, and SharePoint. The library handles OAuth authentication, token refreshing, and datetime conversions automatically. It is actively maintained, with the current stable version being 2.1.9, and receives regular updates.","status":"active","version":"2.1.9","language":"en","source_language":"en","source_url":"https://github.com/O365/python-o365","tags":["microsoft","office365","microsoft-graph","email","calendar","onedrive","sharepoint","outlook","authentication","api-client"],"install":[{"cmd":"pip install O365","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"HTTP client for API requests.","package":"requests"},{"reason":"Microsoft Authentication Library for token acquisition.","package":"msal"},{"reason":"HTML parsing for certain operations.","package":"beautifulsoup4"},{"reason":"Date and time utilities.","package":"python-dateutil"},{"reason":"Determining local timezone.","package":"tzlocal"},{"reason":"Timezone data, especially for newer Python versions.","package":"tzdata"}],"imports":[{"symbol":"Account","correct":"from O365 import Account"},{"note":"Used for persisting authentication tokens to the filesystem.","symbol":"FileSystemTokenBackend","correct":"from O365.utils import FileSystemTokenBackend"}],"quickstart":{"code":"import os\nfrom O365 import Account\nfrom O365.utils import FileSystemTokenBackend\n\nCLIENT_ID = os.environ.get('O365_CLIENT_ID', 'your_client_id')\nCLIENT_SECRET = os.environ.get('O365_CLIENT_SECRET', 'your_client_secret')\n# Optional: TENANT_ID is required for 'credentials' auth_flow_type\nTENANT_ID = os.environ.get('O365_TENANT_ID', None)\n\ncredentials = (CLIENT_ID, CLIENT_SECRET)\n\n# Configure token storage. Create a 'o365_token' directory if it doesn't exist.\ntoken_backend = FileSystemTokenBackend(token_path='o365_token', token_filename='o365_token.txt')\n\n# Initialize Account with credentials and token backend\n# For interactive login (default):\naccount = Account(credentials, token_backend=token_backend)\n\n# For app-only login (client credentials flow):\n# account = Account(credentials, token_backend=token_backend, auth_flow_type='credentials', tenant_id=TENANT_ID)\n\n# Define necessary scopes for your application (e.g., Mail.ReadWrite, Mail.Send)\n# You can use scope helpers: from O365.scopes import MSGraphScopeBuilder; scopes = MSGraphScopeBuilder.for_mail().build()\nrequested_scopes = ['basic', 'offline_access', 'Mail.ReadWrite', 'Mail.Send']\n\nif not account.is_authenticated:\n    print('Authenticating...')\n    # The authenticate method will print a URL. Visit it, log in, and paste the redirect URL back.\n    if account.authenticate(scopes=requested_scopes) is False:\n        raise RuntimeError('Authentication Failed. Check your credentials, scopes, and token_path.')\n    print('Authentication successful!')\nelse:\n    print('Already authenticated.')\n\n# Now you can interact with the O365 services, e.g., send an email\nm = account.new_message()\nm.to.add('recipient@example.com')\nm.subject = 'Hello from O365 Python Library!'\nm.body = \"This is a test email sent using the o365 library.\"\nif m.send():\n    print('Email sent successfully!')\nelse:\n    print('Failed to send email.')\n","lang":"python","description":"This quickstart demonstrates how to authenticate with Microsoft Graph using `o365` and then send a simple email. It uses environment variables for `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID` (if applicable) and shows how to set up `FileSystemTokenBackend` for persistent token storage. The default authentication flow is interactive, requiring user consent via a console-provided URL. Ensure your Azure AD application is registered with the correct redirect URI and API permissions (scopes)."},"warnings":[{"fix":"Re-authenticate all existing `o365` applications to obtain new tokens. Ensure `msal` is correctly installed as a dependency.","message":"Version 2.1 introduced a breaking change by removing custom authentication in favor of `msal`. Existing applications will require a new authentication flow and older access tokens will no longer work.","severity":"breaking","affected_versions":">=2.1.0"},{"fix":"Upgrade your Python environment to 3.10 or newer. If using the old query style, migrate to `QueryBuilder` for future compatibility, although the old query remains interchangeable for other methods for now.","message":"Python 3.9 support was removed in version 2.1.7. Additionally, the 'Old Query' syntax was deprecated in favor of the new `QueryBuilder`.","severity":"breaking","affected_versions":">=2.1.7"},{"fix":"Ensure your application is registered in Azure AD with the 'Web' platform and a redirect URI (e.g., `http://localhost:8000`). Grant the necessary delegated or application permissions (scopes, e.g., `Mail.ReadWrite`, `Mail.Send`, `offline_access`). For `auth_flow_type='credentials'`, you must provide the `tenant_id` and ensure appropriate application permissions are granted.","message":"Microsoft deprecated basic authentication for Office 365 APIs on November 1st, 2018. `o365` exclusively uses OAuth authentication. Incorrect Azure AD application registration, insufficient API permissions (scopes), or an incorrect `tenant_id` (especially for client credentials flow) are common causes of authentication failures (e.g., 'AADSTS' errors).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement a `TokenBackend` appropriate for your environment (e.g., `FileSystemTokenBackend` for local storage or cloud-specific backends) and ensure that the token storage location is protected. Consider using a `cryptography_manager` with your `TokenBackend` for encryption.","message":"Authentication tokens contain sensitive information and must be securely stored. By default, `o365` attempts to store tokens, but custom token backends (e.g., `FileSystemTokenBackend`, `FirestoreTokenBackend`) are crucial for production environments to manage token persistence and protection.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}