Add Teams and Outlook examples: tags, clone, shared channels, archive lifecycle, message lifecycle, folder management, contacts, meeting finder

Author: Vadim

examples/outlook/README.md

@@ -16,6 +16,8 @@ Microsoft Graph.
 | `Mail.Read` (delegated) | Read mail tips and message properties | [Mail permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#mail-permissions) |
 | `Reports.Read.All` (delegated) | Access email and mailbox usage reports | [Reports permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#reports-permissions) |
 | `User.Read.All` (delegated or app) | Read user properties for mailbox audit, shared mailboxes, forwarding detection | [User permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#user-permissions) |
+| `Contacts.ReadWrite` (delegated) | Create, read, update, delete personal contacts | [Contacts permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#contacts-permissions) |
+| `Place.Read.All` (delegated) | List rooms and room lists | [Places permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#places-permissions) |
 
 ---
 
@@ -61,6 +63,10 @@ flowchart LR
 | **Mailbox audit** — auto-replies, mailbox settings report | [`mailboxes/report.py`](./mailboxes/report.py) | Bulk audit of user mailbox configurations |
 | **Shared mailboxes** — list and check configuration | [`shared_mailboxes/report.py`](./shared_mailboxes/report.py) | Discover and validate shared mailbox setup |
 | **Mail flow audit** — detect external forwarding | [`mail_flow/forwarding_report.py`](./mail_flow/forwarding_report.py) | Security audit — identify users forwarding mail externally |
+| **Message lifecycle** — reply, forward, move, copy in one flow | [`messages/lifecycle.py`](./messages/lifecycle.py) | Common post-receive operations: create reply draft → edit → send, forward to someone else, move and copy across folders |
+| **Folder management** — create, empty, mark-all-read, permanent delete | [`messages/folders.py`](./messages/folders.py) | Mailbox cleanup and compliance: create folder tree, empty content (including subfolders), bulk mark read, hard delete |
+| **Contacts** — create, update, delete with contact folders | [`contacts/manage.py`](./contacts/manage.py) | Full personal contact CRUD with contact folder organization, multiple email addresses, and lifecycle management |
+| **Meeting finder + rooms** — suggest time slots, list rooms, check availability | [`calendars/meeting_finder.py`](./calendars/meeting_finder.py) | Scheduling assistant pattern: find meeting times with attendees and rooms, list places/room lists, room capacity info |
 
 ---
 

examples/outlook/calendars/meeting_finder.py

@@ -0,0 +1,95 @@
+"""
+Meeting finder: suggest optimal time slots and resolve rooms.
+
+Brings together three related patterns:
+  1. Find available meeting times that work for all attendees.
+  2. List room lists and rooms in the tenant.
+  3. Get free/busy schedule for a room across a time window.
+
+Useful for scheduling assistants, booking flows, and room
+management tooling.
+
+Requires delegated permissions:
+    Calendars.ReadWrite          Create and manage events
+    MailboxSettings.Read         Read user availability
+    Place.Read.All               List rooms and room lists
+
+https://learn.microsoft.com/en-us/graph/api/user-findmeetingtimes
+https://learn.microsoft.com/en-us/graph/api/resources/place
+"""
+
+from datetime import datetime, timedelta, timezone
+
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+
+def main():
+    client = GraphClient(tenant=test_tenant).with_username_and_password(test_client_id, test_username, test_password)
+
+    # -- Step 1: list room lists and rooms in the tenant --
+    print("Places (room lists and rooms):")
+    all_places = client.places.get().execute_query()
+    for p in all_places:
+        print(f"  {p.display_name:45s}  type={p.entity_type_name}")
+    print()
+
+    # Try to get room lists specifically
+    room_lists = client.places.room_lists.get().execute_query()
+    if room_lists:
+        print("Room lists:")
+        for rl in room_lists:
+            print(f"  {rl.display_name:45s}  {rl.email_address or ''}")
+            # Get rooms in this list
+            try:
+                rooms = rl.rooms.get().execute_query()
+                for room in rooms:
+                    print(f"    ↳ {room.display_name:40s}  {room.email_address or ''}  ({room.capacity or '?'} seats)")
+            except Exception:
+                pass
+    else:
+        print("(No room lists found — room list management may need Place.Read.All)")
+
+    # -- Step 2: find meeting times for next week --
+    now = datetime.now(timezone.utc)
+    start_time = now + timedelta(days=1)
+    end_time = now + timedelta(days=7)
+
+    # Collect room email addresses if available
+    attendee_smtp = ["meganb@contoso.onmicrosoft.com"]
+    if room_lists:
+        for rl in room_lists[:1]:  # first room list
+            try:
+                rooms = rl.rooms.get().execute_query()
+                attendee_smtp.extend(r.email_address for r in rooms[:2] if r.email_address)
+            except Exception:
+                pass
+
+    print(f"\nFinding meeting times for: {', '.join(attendee_smtp)}")
+    print(f"  Window: {start_time.strftime('%Y-%m-%d %H:%M')} — {end_time.strftime('%Y-%m-%d %H:%M')}")
+
+    suggestions = client.me.find_meeting_times(
+        attendees=attendee_smtp,
+        meeting_duration=timedelta(hours=1),
+        max_candidates=5,
+    ).execute_query()
+
+    if suggestions and hasattr(suggestions, "value") and suggestions.value:
+        print(f"\nSuggested times ({len(suggestions.value)} candidate(s)):\n")
+        # The value is a MeetingTimeSuggestionsResult
+        result = suggestions.value
+        if hasattr(result, "meeting_time_suggestions") and result.meeting_time_suggestions:
+            for s in result.meeting_time_suggestions:
+                slot = s.meeting_time_slot
+                print(f"  {slot.start.strftime('%Y-%m-%d %H:%M')} — {slot.end.strftime('%H:%M')}  (confidence: {s.confidence})")
+                if hasattr(s, "locations") and s.locations:
+                    for loc in s.locations:
+                        print(f"    Location: {loc.display_name}")
+        else:
+            print("  (no detailed suggestions — check permissions)")
+    else:
+        print("  No meeting suggestions returned.")
+
+
+if __name__ == "__main__":
+    main()

examples/outlook/contacts/manage.py

@@ -0,0 +1,68 @@
+"""
+Contact management: create, read, update, and delete personal contacts.
+
+Covers the full CRUD lifecycle for Outlook contacts, including
+contact folders for organization.
+
+Requires delegated permission ``Contacts.ReadWrite``.
+
+https://learn.microsoft.com/en-us/graph/api/resources/contact
+"""
+
+import sys
+
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+
+def main():
+    client = GraphClient(tenant=test_tenant).with_username_and_password(test_client_id, test_username, test_password)
+
+    # -- Step 1: create a contact folder --
+    folder_name = "SDK Demo Contacts"
+    folders = client.me.contact_folders.get().execute_query()
+    folder = next((f for f in folders if f.display_name == folder_name), None)
+
+    if folder is None:
+        folder = client.me.contact_folders.add(folder_name).execute_query()
+        print(f"Created contact folder: '{folder.display_name}' (id: {folder.id})")
+    else:
+        print(f"Using existing folder: '{folder.display_name}'")
+
+    # -- Step 2: create a contact --
+    contact = (
+        folder.contacts.add(
+            given_name="Maria",
+            surname="Andersen",
+            email_address="mariaa@contoso.onmicrosoft.com",
+            business_phone="+1 555 123 4567",
+        )
+        .execute_query()
+    )
+    print(f"Created contact: {contact.display_name}  ({contact.primary_email_address.address})")
+
+    # -- Step 3: update fields --
+    contact.set_property("mobilePhone", "+1 555 987 6543")
+    contact.set_property("jobTitle", "Senior Engineer")
+    contact.update().execute_query()
+    print(f"Updated contact: mobile & job title set.")
+
+    # -- Step 4: add a second email address --
+    # The email_addresses property is a collection — append to it
+    contact.email_addresses.add("maria.andersen@personal.com")
+    contact.update().execute_query()
+    print(f"Added secondary email.")
+
+    # -- Step 5: list all contacts in the folder --
+    contacts = folder.contacts.get().execute_query()
+    print(f"\nContacts in '{folder_name}' ({len(contacts)}):")
+    for c in contacts:
+        print(f"  {c.display_name:25s}  {c.primary_email_address.address or '':35s}  {c.mobile_phone or '':15s}")
+
+    # -- Step 6: delete the contact --
+    contact.delete_object().execute_query()
+    print(f"\n✓ Deleted contact: {contact.display_name}")
+
+
+if __name__ == "__main__":
+    main()

examples/outlook/messages/folders.py

@@ -0,0 +1,81 @@
+"""
+Mail folder management: create, navigate, empty, mark all read, and
+permanent-delete folders.
+
+Mailbox cleanup and compliance workflows often need bulk operations
+on folders — purge old content, reset unread counts, or remove
+stale folder trees.
+
+Requires delegated permission ``Mail.ReadWrite`` and
+``MailboxSettings.ReadWrite``.
+
+https://learn.microsoft.com/en-us/graph/api/resources/mailfolder
+"""
+
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+
+def walk_folders(client: GraphClient, parent_path="inbox", indent=0):
+    """Recursively list folders and subfolders with item counts."""
+    parent = client.me.mail_folders[parent_path]
+    parent.select(["displayName", "totalItemCount", "unreadItemCount"]).expand(["childFolders"]).execute_query()
+
+    prefix = "  " * indent
+    print(
+        f"{prefix}{parent.display_name}  "
+        f"({parent.total_item_count or 0} items, "
+        f"{parent.unread_item_count or 0} unread)"
+    )
+
+    if parent.child_folders:
+        for child in parent.child_folders:
+            walk_folders(client, child.id, indent + 1)
+
+
+def main():
+    client = GraphClient(tenant=test_tenant).with_username_and_password(test_client_id, test_username, test_password)
+
+    # -- Step 1: create a folder --
+    inbox = client.me.mail_folders["inbox"]
+    new_folder = inbox.child_folders.add("Cleanup Test").execute_query()
+    print(f"Created folder: '{new_folder.display_name}' (id: {new_folder.id})")
+
+    # -- Step 2: create a child subfolder --
+    sub_folder = new_folder.child_folders.add("Subfolder").execute_query()
+    print(f"Created subfolder: '{sub_folder.display_name}'")
+
+    # -- Step 3: navigate the tree --
+    print("\nMailbox folder tree:")
+    walk_folders(client)
+    print()
+
+    # -- Step 4: mark all items as read in a folder --
+    # Move one message into the folder first so we have something
+    latest = client.me.mail_folders["inbox"].messages.top(1).get().execute_query()
+    if latest:
+        latest[0].move(new_folder.id).execute_query()
+        print("Moved 1 message into folder (to simulate unread).")
+
+    new_folder.mark_all_items_as_read().execute_query()
+    print(f"✓ Marked all items as read in '{new_folder.display_name}'.")
+
+    # -- Step 5: empty the folder (delete all items) --
+    new_folder.empty(delete_sub_folders=True).execute_query()
+    print(f"✓ Emptied '{new_folder.display_name}' (including subfolders).")
+
+    # -- Step 6: permanent delete removes the folder itself --
+    # Re-fetch the folder reference
+    target = client.me.mail_folders[new_folder.id]
+    target.permanent_delete().execute_query()
+    print("✓ Permanent-deleted the folder.")
+
+    # Verify it's gone
+    try:
+        client.me.mail_folders[new_folder.id].get().execute_query()
+    except Exception:
+        print("  Confirmed: folder no longer exists.")
+
+
+if __name__ == "__main__":
+    main()

examples/outlook/messages/lifecycle.py

@@ -0,0 +1,79 @@
+"""
+Message lifecycle: reply, forward, move, and copy messages.
+
+Covers the most common post-receive operations:
+  - Reply to sender (with modified body)
+  - Forward to another recipient
+  - Move to a different folder
+  - Copy to a different folder
+
+The pattern: create a draft → optionally edit → save or send.
+
+Requires delegated permission ``Mail.ReadWrite`` and ``Mail.Send``.
+
+https://learn.microsoft.com/en-us/graph/api/message-createreply
+https://learn.microsoft.com/en-us/graph/api/message-forward
+https://learn.microsoft.com/en-us/graph/api/message-move
+https://learn.microsoft.com/en-us/graph/api/message-copy
+"""
+
+import sys
+
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+
+def get_latest_inbox_message(client: GraphClient):
+    """Return the most recent message in the inbox, or None."""
+    messages = client.me.mail_folders["inbox"].messages.top(1).get().execute_query()
+    return messages[0] if len(messages) > 0 else None
+
+
+def main():
+    client = GraphClient(tenant=test_tenant).with_username_and_password(test_client_id, test_username, test_password)
+
+    # -- Step 1: pick a message to work with --
+    message = get_latest_inbox_message(client)
+    if message is None:
+        sys.exit("No messages in inbox.")
+
+    # Load subject and body for display
+    message.select(["subject", "body"]).execute_query()
+    print(f"Source message: \"{message.subject}\"\n")
+
+    # -- Step 2: reply --
+    draft = message.create_reply().execute_query()
+    # Draft body is auto-populated; append a line
+    body = draft.body.get_property("content", "")
+    draft.set_property("body", {"contentType": "Text", "content": body + "\n\n---\nSent via Microsoft Graph SDK"})
+    draft.update().execute_query()
+    draft.send().execute_query()
+    print("✓ Reply sent (with appended signature).")
+
+    # -- Step 3: forward --
+    forward_to = "meganb@contoso.onmicrosoft.com"
+    message.forward(to_recipients=[forward_to], comment="FYI — see below.").execute_query()
+    print(f"✓ Forwarded to {forward_to}.")
+
+    # -- Step 4: move to a subfolder --
+    # Ensure a subfolder exists
+    inbox = client.me.mail_folders["inbox"]
+    child_folders = inbox.child_folders.get().execute_query()
+    archive_folder = next((f for f in child_folders if f.display_name == "Archive"), None)
+
+    if archive_folder is None:
+        archive_folder = inbox.child_folders.add("Archive").execute_query()
+        print(f"  (Created 'Archive' folder)")
+
+    moved = message.move(archive_folder.id).execute_query()
+    print(f"✓ Moved to '{archive_folder.display_name}' (new id: {moved.id})")
+
+    # -- Step 5: copy back to inbox --
+    inbox = client.me.mail_folders["inbox"]
+    # Refresh the message reference from its new location
+    copied = client.me.messages[moved.id].copy(inbox.id).execute_query()
+    print(f"✓ Copied back to Inbox.")
+
+
+if __name__ == "__main__":
+    main()

examples/teams/README.md

@@ -17,6 +17,9 @@ patterns.
 | `Chat.ReadWrite` (delegated) | Create and message in chats | [Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#teams-permissions) |
 | `TeamSettings.ReadWrite.All` (application) | Audit and remediate team settings | [Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#teams-permissions) |
 | `Directory.Read.All` (application) | Enumerate tenant-wide groups and deleted items | [Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#directory-permissions) |
+| `TeamworkTag.ReadWrite.All` (delegated) | Create and manage tags | [Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#teams-permissions) |
+| `ChannelMember.ReadWrite.All` (delegated/application) | Manage shared channel members | [Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#teams-permissions) |
+| `TeamworkTag.Read.All` (application) | Read tags across all teams | [Microsoft Graph permissions](https://learn.microsoft.com/en-us/graph/permissions-reference#teams-permissions) |
 
 Admin consent is required for all permissions above.
 
@@ -68,6 +71,11 @@ conversations not tied to any team/channel.
 | **Usage report** — team counts and user activity over D7/D30/D90 | [`reports/usage.py`](./reports/usage.py) | Adoption tracking, chargeback, and inactivity detection across multiple time windows |
 | **Inactive channels** — channels with no recent messages across all teams | [`find_inactive_channels.py`](./find_inactive_channels.py) | Identify channel sprawl and candidates for archiving |
 | **App inventory** — report installed apps across all teams | [`apps/report.py`](./apps/report.py) | Detect shadow IT and track app adoption across the tenant |
+| **Create tag** — create a tag and assign members in a team | [`tags/create_and_assign.py`](./tags/create_and_assign.py) | Provision @mention groups for routing and alerts. Resolves users by email then creates tag with members |
+| **Tag inventory** — report all tags across every team with member count | [`tags/report.py`](./tags/report.py) | Shows which teams use tags, identifies untagged teams and stale tags across the tenant |
+| **Clone team** — clone channels, apps, tabs, settings, and/or members | [`clone_team.py`](./clone_team.py) | Bootstrap new projects from a template team. Uses `ClonableTeamParts` bitset + async polling with progress |
+| **Shared channel** — create shared channel, share with other team, manage access | [`channels/shared.py`](./channels/shared.py) | Cross-team collaboration via shared channels. Covers creation, sharing, allowed members, and access check |
+| **Archive lifecycle** — find inactive teams, archive with audit mode, unarchive | [`archive_lifecycle.py`](./archive_lifecycle.py) | Compliance workflow: scan teams for inactivity, archive candidates, with ready-to-paste unarchive snippet |
 
 ---
 ---