Address Book

AddressBook groups the functionality of both the Contact Folders and Contacts. Outlook Distribution Groups are not supported (By the Microsoft API’s).

These are the scopes needed to work with the AddressBook and Contact classes.

Raw Scope

Included in Scope Helper

Description

Contacts.Read

address_book

To only read my personal contacts

Contacts.Read.Shared

address_book_shared

To only read another user / shared mailbox contacts

Contacts.ReadWrite

address_book_all

To read and save personal contacts

Contacts.ReadWrite.Shared

address_book_all_shared

To read and save contacts from another user / shared mailbox

User.ReadBasic.All

users

To only read basic properties from users of my organization (User.Read.All requires administrator consent).

Contact Folders

Represents a Folder within your Contacts Section in Office 365. AddressBook class represents the parent folder (it’s a folder itself).

You can get any folder in your address book by requesting child folders or filtering by name.

address_book = account.address_book()

contacts = address_book.get_contacts(limit=None)  # get all the contacts in the Personal Contacts root folder

work_contacts_folder = address_book.get_folder(folder_name='Work Contacts')  # get a folder with 'Work Contacts' name

message_to_all_contats_in_folder = work_contacts_folder.new_message()  # creates a draft message with all the contacts as recipients

message_to_all_contats_in_folder.subject = 'Hallo!'
message_to_all_contats_in_folder.body = """
George Best quote:

If you'd given me the choice of going out and beating four men and smashing a goal in
from thirty yards against Liverpool or going to bed with Miss World,
it would have been a difficult choice. Luckily, I had both.
"""
message_to_all_contats_in_folder.send()

# querying folders is easy:
child_folders = address_book.get_folders(25) # get at most 25 child folders

for folder in child_folders:
    print(folder.name, folder.parent_id)

# creating a contact folder:
address_book.create_child_folder('new folder')

Global Address List

MS Graph API has no concept such as the Outlook Global Address List. However you can use the Users API to access all the users within your organization.

Without admin consent you can only access a few properties of each user such as name and email and little more. You can search by name or retrieve a contact specifying the complete email.

  • Basic Permission needed is Users.ReadBasic.All (limit info)

  • Full Permission is Users.Read.All but needs admin consent.

To search the Global Address List (Users API):

global_address_list = account.directory()

# for backwards compatibility only this also works and returns a Directory object:
# global_address_list = account.address_book(address_book='gal')

# start a new query:
q = global_address_list.new_query('display_name')
q.startswith('George Best')

for user in global_address_list.get_users(query=q):
    print(user)

To retrieve a contact by their email:

contact = global_address_list.get_user('example@example.com')
Contacts

Everything returned from an AddressBook instance is a Contact instance. Contacts have all the information stored as attributes

Creating a contact from an AddressBook:

new_contact = address_book.new_contact()

new_contact.name = 'George Best'
new_contact.job_title = 'football player'
new_contact.emails.add('george@best.com')

new_contact.save()  # saved on the cloud

message = new_contact.new_message()  #  Bonus: send a message to this contact

# ...

new_contact.delete()  # Bonus: deleted from the cloud