Adds some examples in README.md. Improvements in create_contact. Some minor fixes

Author: ingmferrer

README.md

@@ -68,7 +68,15 @@ response = client.mail.get_message(message_id)
 
 #### Send mail
 ```
-response = client.mail.send_mail(subject, content, to_recipients)
+data = {
+    subject="Meet for lunch?",
+    content="The new cafeteria is open.",
+    content_type="text",
+    to_recipients=["[email protected]"],
+    cc_recipients=None,
+    save_to_sent_items=True,
+}
+response = client.mail.send_mail(**data)
 ```
 
 ### Notes
@@ -110,7 +118,24 @@ response = client.calendar.get_event(event_id)
 
 #### Create calendar event
 ```
-response = client.calendar.create_event(subject, content, start_datetime,start_timezone, end_datetime, end_timezone, location, calendar, content_type)
+from datetime import datetime, timedelta
+
+start_datetime = datetime.now() + timedelta(days=1) # tomorrow
+end_datetime = datetime.now() + timedelta(days=1, hours=1) # tomorrow + one hour
+timezone = "America/Bogota"
+
+data = {
+    "calendar_id": "CALENDAR_ID",
+    "subject": "Let's go for lunch",
+    "content": "Does noon work for you?",
+    "content_type": "text",
+    "start_datetime": start_datetime,
+    "start_timezone": timezone,
+    "end_datetime": end_datetime,
+    "end_timezone": timezone,
+    "location": "Harry's Bar",
+}
+response = client.calendar.create_event(**data)
 ```
 
 #### Get calendars
@@ -136,12 +161,21 @@ response = client.contacts.list_contacts()
 
 #### Create contact
 ```
-response = client.contacts.create_contact()
-```
-
-#### Create contact in specific folder
-```
-response = client.contacts.create_contact_in_folder(folder_id)
+data = {
+    "given_name": "Pavel",
+    "surname": "Bansky",
+    "email_addresses": [
+        {
+            "address": "[email protected]",
+            "name": "Pavel Bansky"
+        }
+    ],
+    "business_phones": [
+        "+1 732 555 0102"
+    ],
+    "folder_id": None,
+}
+response = client.contacts.create_contact(**data)
 ```
 
 #### Get contact folders

microsoftgraph/calendar.py

@@ -101,6 +101,7 @@ def create_event(
             },
             "location": {"displayName": location},
         }
+        body.update(kwargs)
         url = "me/calendars/{}/events".format(calendar_id) if calendar_id is not None else "me/events"
         return self._client._post(self._client.base_url + url, json=body)
 

microsoftgraph/contacts.py

@@ -1,3 +1,4 @@
+import json
 from microsoftgraph.decorators import token_required
 from microsoftgraph.response import Response
 
@@ -26,8 +27,7 @@ def get_contact(self, contact_id: str, params: dict = None) -> Response:
         Returns:
             Response: Microsoft Graph Response.
         """
-        url = "{0}me/contacts/{1}".format(self._client.base_url, contact_id)
-        return self._client._get(url, params=params)
+        return self._client._get(self._client.base_url + "me/contacts/{}".format(contact_id), params=params)
 
     @token_required
     def list_contacts(self, params: dict = None) -> Response:
@@ -41,35 +41,47 @@ def list_contacts(self, params: dict = None) -> Response:
         Returns:
             Response: Microsoft Graph Response.
         """
-        url = "{0}me/contacts".format(self._client.base_url)
-        return self._client._get(url, params=params)
+        return self._client._get(self._client.base_url + "me/contacts", params=params)
 
     @token_required
-    def create_contact(self, **kwargs) -> Response:
-        """Add a contact to the root Contacts folder.
-
-        https://docs.microsoft.com/en-us/graph/api/user-post-contacts?view=graph-rest-1.0&tabs=http
-
-        Returns:
-            Response: Microsoft Graph Response.
-        """
-        url = "{0}me/contacts".format(self._client.base_url)
-        return self._client._post(url, **kwargs)
-
-    @token_required
-    def create_contact_in_folder(self, folder_id: str, **kwargs) -> Response:
-        """Add a contact to another contact folder.
+    def create_contact(
+        self,
+        given_name: str,
+        surname: str,
+        email_addresses: list,
+        business_phones: list,
+        folder_id: str = None,
+        **kwargs
+    ) -> Response:
+        """Add a contact to the root Contacts folder or to the contacts endpoint of another contact folder.
 
         https://docs.microsoft.com/en-us/graph/api/user-post-contacts?view=graph-rest-1.0&tabs=http
 
         Args:
-            folder_id (str): Unique identifier of the contact folder.
+            given_name (str): The contact's given name.
+            surname (str): The contact's surname.
+            email_addresses (list): The contact's email addresses.
+            business_phones (list): The contact's business phone numbers.
+            folder_id (str, optional): Unique identifier of the contact folder. Defaults to None.
 
         Returns:
             Response: Microsoft Graph Response.
         """
-        url = "{0}me/contactFolders/{1}/contacts".format(self._client.base_url, folder_id)
-        return self._client._post(url, **kwargs)
+        if isinstance(email_addresses, str):
+            email_addresses = [{"address": email_addresses, "name": "{} {}".format(given_name, surname)}]
+
+        if isinstance(business_phones, str):
+            business_phones = [business_phones]
+
+        body = {
+            "givenName": given_name,
+            "surname": surname,
+            "emailAddresses": email_addresses,
+            "businessPhones": business_phones,
+        }
+        body.update(kwargs)
+        url = "me/contactFolders/{}/contacts".format(folder_id) if folder_id else "me/contacts"
+        return self._client._post(self._client.base_url + url, json=body)
 
     @token_required
     def list_contact_folders(self, params: dict = None) -> Response:
@@ -83,8 +95,7 @@ def list_contact_folders(self, params: dict = None) -> Response:
         Returns:
             Response: Microsoft Graph Response.
         """
-        url = "{0}me/contactFolders".format(self._client.base_url)
-        return self._client._get(url, params=params)
+        return self._client._get(self._client.base_url + "me/contactFolders", params=params)
 
     @token_required
     def create_contact_folder(self, **kwargs) -> Response:
@@ -95,5 +106,4 @@ def create_contact_folder(self, **kwargs) -> Response:
         Returns:
             Response: Microsoft Graph Response.
         """
-        url = "{0}me/contactFolders".format(self._client.base_url)
-        return self._client._post(url, **kwargs)
+        return self._client._post(self._client.base_url + "me/contactFolders", **kwargs)

microsoftgraph/mail.py

@@ -41,6 +41,7 @@ def send_mail(
         content_type: str = "HTML",
         attachments: list = None,
         save_to_sent_items: bool = True,
+        **kwargs,
     ) -> Response:
         """Send the message specified in the request body using either JSON or MIME format.
 
@@ -59,11 +60,21 @@ def send_mail(
             Response: Microsoft Graph Response.
         """
         # Create recipient list in required format.
-        to_recipient_list = [{"EmailAddress": {"Address": address}} for address in to_recipients]
-
-        cc_recipient_list = []
-        if cc_recipients:
-            cc_recipient_list = [{"EmailAddress": {"Address": address}} for address in cc_recipients]
+        if isinstance(to_recipients, list):
+            if all([isinstance(e, str) for e in to_recipients]):
+                to_recipients = [{"EmailAddress": {"Address": address}} for address in to_recipients]
+        elif isinstance(to_recipients, str):
+            to_recipients = [{"EmailAddress": {"Address": to_recipients}}]
+        else:
+            raise Exception("to_recipients value is invalid.")
+
+        if cc_recipients and isinstance(cc_recipients, list):
+            if all([isinstance(e, str) for e in cc_recipients]):
+                cc_recipients = [{"EmailAddress": {"Address": address}} for address in cc_recipients]
+        elif cc_recipients and isinstance(cc_recipients, str):
+            cc_recipients = [{"EmailAddress": {"Address": cc_recipients}}]
+        else:
+            cc_recipients = []
 
         # Create list of attachments in required format.
         attached_files = []
@@ -86,12 +97,13 @@ def send_mail(
             "Message": {
                 "Subject": subject,
                 "Body": {"ContentType": content_type, "Content": content},
-                "ToRecipients": to_recipient_list,
-                "ccRecipients": cc_recipient_list,
+                "ToRecipients": to_recipients,
+                "ccRecipients": cc_recipients,
                 "Attachments": attached_files,
             },
             "SaveToSentItems": save_to_sent_items,
         }
+        email_msg.update(kwargs)
 
         # Do a POST to Graph's sendMail API and return the response.
         return self._client._post(self._client.base_url + "me/sendMail", json=email_msg)

microsoftgraph/webhooks.py

@@ -66,7 +66,7 @@ def renew_subscription(self, subscription_id: str, expiration_datetime: datetime
             Response: Microsoft Graph Response.
         """
         if isinstance(expiration_datetime, datetime):
-            expiration_datetime = expiration_datetime.strftime("%Y-%m-%dT%H:%M:%S.%f")
+            expiration_datetime = format_time(expiration_datetime, is_webhook=True)
 
         data = {"expirationDateTime": expiration_datetime}
         return self._client._patch(self._client.base_url + "subscriptions/{}".format(subscription_id), json=data)