#841: improvements to User.send_mail method

examples/outlook/messages/send_html.py

@@ -0,0 +1,24 @@
+"""
+Send the message specified in the request body using either JSON or MIME format.
+
+The example is adapted from https://docs.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0
+"""
+
+from office365.graph_client import GraphClient
+from office365.outlook.mail.item_body import ItemBody
+from tests import (
+    test_client_id,
+    test_password,
+    test_tenant,
+    test_user_principal_name_alt,
+    test_username,
+)
+
+client = GraphClient.with_username_and_password(
+    test_tenant, test_client_id, test_username, test_password
+)
+client.me.send_mail(
+    subject="Meet for lunch?",
+    body=ItemBody.create_html("<h1>The new cafeteria is open.</h1>"),
+    to_recipients=["[email protected]", test_user_principal_name_alt],
+).execute_query()

office365/directory/users/user.py

@@ -1,6 +1,6 @@
 import json
 from datetime import datetime
-from typing import Optional
+from typing import List, Optional
 
 from office365.communications.onlinemeetings.collection import OnlineMeetingCollection
 from office365.communications.presences.presence import Presence
@@ -46,6 +46,7 @@
 from office365.outlook.contacts.folder import ContactFolder
 from office365.outlook.convert_id_result import ConvertIdResult
 from office365.outlook.mail.folders.collection import MailFolderCollection
+from office365.outlook.mail.item_body import ItemBody
 from office365.outlook.mail.mailbox_settings import MailboxSettings
 from office365.outlook.mail.messages.collection import MessageCollection
 from office365.outlook.mail.messages.message import Message
@@ -201,6 +202,7 @@ def send_mail(
         bcc_recipients=None,
         save_to_sent_items=False,
     ):
+        # type: (str, str|ItemBody, List[str], List[str], List[str], bool) -> Message
         """Send a new message on the fly
 
         :param str subject: The subject of the message.

office365/onedrive/sharepoint_ids.py

@@ -5,13 +5,30 @@ class SharePointIds(ClientValue):
     """The SharePointIds resource groups the various identifiers for an item stored in a SharePoint site or OneDrive
     for Business into a single structure."""
 
-    def __init__(self, list_id=None, list_item_id=None, list_item_unique_id=None):
+    def __init__(
+        self,
+        list_id=None,
+        list_item_id=None,
+        list_item_unique_id=None,
+        siteId=None,
+        siteUrl=None,
+        tenantId=None,
+        webId=None,
+    ):
         """
         :param str list_id: The unique identifier (guid) for the item's list in SharePoint.
         :param str list_item_id: An integer identifier for the item within the containing list.
         :param str list_item_unique_id: The unique identifier (guid) for the item within OneDrive for Business
             or a SharePoint site.
+        :param str siteId: The unique identifier (guid) for the item's site collection (SPSite).
+        :param str siteUrl: The SharePoint URL for the site that contains the item.
+        :param str tenantId: The unique identifier (guid) for the tenancy.
+        :param str webId: The unique identifier (guid) for the item's site (SPWeb).
         """
         self.listId = list_id
         self.listItemId = list_item_id
         self.listItemUniqueId = list_item_unique_id
+        self.siteId = siteId
+        self.siteUrl = siteUrl
+        self.tenantId = tenantId
+        self.webId = webId

office365/outlook/mail/item_body.py

@@ -6,13 +6,22 @@ class ItemBody(ClientValue):
 
     def __init__(self, content=None, content_type="Text"):
         """
-
         :param str content: The content of the item.
         :param str content_type: The type of the content. Possible values are text and html.
         """
         super(ItemBody, self).__init__()
         self.content = content
         self.contentType = content_type
 
+    @staticmethod
+    def create_text(content):
+        # type: (str) -> "ItemBody"
+        return ItemBody(content)
+
+    @staticmethod
+    def create_html(content):
+        # type: (str) -> "ItemBody"
+        return ItemBody(content, "html")
+
     def __repr__(self):
         return self.content

office365/outlook/mail/messages/collection.py

@@ -1,3 +1,5 @@
+from typing import List
+
 from office365.delta_collection import DeltaCollection
 from office365.outlook.mail.item_body import ItemBody
 from office365.outlook.mail.messages.message import Message
@@ -10,6 +12,7 @@ def __init__(self, context, resource_path=None):
         super(MessageCollection, self).__init__(context, Message, resource_path)
 
     def add(self, subject=None, body=None, to_recipients=None, **kwargs):
+        # type: (str, str|ItemBody, List[str], ...) -> Message
         """
         Create a draft of a new message in either JSON or MIME format.
 

office365/outlook/mail/messages/message.py

@@ -1,7 +1,7 @@
 import os
 import uuid
 from datetime import datetime
-from typing import IO, AnyStr, Optional
+from typing import IO, AnyStr, List, Optional
 
 from typing_extensions import Self
 
@@ -42,6 +42,7 @@ def add_extended_property(self, name, value):
         return self
 
     def create_forward(self, to_recipients=None, message=None, comment=None):
+        # type: (List[Recipient], "Message", str) -> Message
         """
         Create a draft to forward an existing message, in either JSON or MIME format.
 
@@ -373,9 +374,7 @@ def sent_datetime(self):
     @property
     def subject(self):
         # type: () -> Optional[str]
-        """
-        The subject of the message.
-        """
+        """The subject of the message."""
         return self.properties.get("subject", None)
 
     @subject.setter

tests/teams/test_channel.py

@@ -72,9 +72,8 @@ def test6_get_primary_channel(self):
     #    self.assertIsNotNone(drive_item.resource_path)
 
     def test8_send_message(self):
-        item_body = ItemBody("Hello world!")
         message = self.__class__.target_channel.messages.add(
-            body=item_body
+            body=ItemBody("Hello world!")
         ).execute_query()
         self.assertIsNotNone(message.id)
         self.__class__.target_message = message