0
# Contacts and Address Book
1

2
Contact management with support for personal contacts, shared address books, contact folders, and contact groups with full CRUD operations.
3

4
## Capabilities
5

6
### Address Book Access
7

8
Access contact services for the authenticated user or other users with proper permissions.
9

10
```python { .api }
11
def address_book(self, resource: str = None) -> AddressBook:
12
    """
13
    Get an address book instance for contact operations.
14
    
15
    Parameters:
16
    - resource: user resource identifier (defaults to authenticated user)
17
    
18
    Returns:
19
    - AddressBook: AddressBook instance for contact operations
20
    """
21

22
class AddressBook:
23
    def __init__(self, parent: Account, main_resource: str = None): ...
24
    
25
    def get_contacts(self, limit: int = None, **filters) -> list[Contact]:
26
        """
27
        Get contacts from the address book.
28
        
29
        Parameters:
30
        - limit: maximum number of contacts to return
31
        - filters: OData query filters
32
        
33
        Returns:
34
        - list[Contact]: List of contact objects
35
        """
36
    
37
    def get_contact(self, contact_id: str) -> Contact:
38
        """
39
        Get a specific contact by ID.
40
        
41
        Parameters:
42
        - contact_id: contact identifier
43
        
44
        Returns:
45
        - Contact: Contact object
46
        """
47
    
48
    def new_contact(self) -> Contact:
49
        """
50
        Create a new contact.
51
        
52
        Returns:
53
        - Contact: New contact object
54
        """
55
```
56

57
### Contact Management
58

59
Create, update, and manage individual contacts with full contact information.
60

61
```python { .api }
62
class Contact:
63
    @property
64
    def display_name(self) -> str:
65
        """Contact display name."""
66
    
67
    @property
68
    def given_name(self) -> str:
69
        """First name."""
70
    
71
    @property
72
    def surname(self) -> str:
73
        """Last name."""
74
    
75
    @property
76
    def email_addresses(self) -> list[dict]:
77
        """List of email addresses."""
78
    
79
    @property
80
    def phone_numbers(self) -> list[dict]:
81
        """List of phone numbers."""
82
    
83
    @property
84
    def addresses(self) -> list[dict]:
85
        """List of postal addresses."""
86
    
87
    @property
88
    def company_name(self) -> str:
89
        """Company name."""
90
    
91
    @property
92
    def job_title(self) -> str:
93
        """Job title."""
94
    
95
    @property
96
    def department(self) -> str:
97
        """Department."""
98
    
99
    @property
100
    def birthday(self) -> datetime:
101
        """Birthday."""
102
    
103
    @property
104
    def notes(self) -> str:
105
        """Personal notes about the contact."""
106
    
107
    def save(self) -> bool:
108
        """Save changes to the contact."""
109
    
110
    def delete(self) -> bool:
111
        """Delete this contact."""
112
    
113
    def add_email(self, address: str, name: str = None, 
114
                  address_type: str = 'work') -> bool:
115
        """
116
        Add an email address to the contact.
117
        
118
        Parameters:
119
        - address: email address
120
        - name: display name for the email
121
        - address_type: 'work', 'home', or 'other'
122
        
123
        Returns:
124
        - bool: True if successful
125
        """
126
    
127
    def add_phone(self, number: str, phone_type: str = 'work') -> bool:
128
        """
129
        Add a phone number to the contact.
130
        
131
        Parameters:
132
        - number: phone number
133
        - phone_type: 'work', 'home', 'mobile', or 'other'
134
        
135
        Returns:
136
        - bool: True if successful
137
        """
138
    
139
    def add_address(self, street: str = None, city: str = None,
140
                   state: str = None, postal_code: str = None,
141
                   country: str = None, address_type: str = 'work') -> bool:
142
        """
143
        Add a postal address to the contact.
144
        
145
        Parameters:
146
        - street: street address
147
        - city: city name
148
        - state: state or province
149
        - postal_code: postal/zip code
150
        - country: country name
151
        - address_type: 'work', 'home', or 'other'
152
        
153
        Returns:
154
        - bool: True if successful
155
        """
156
```
157

158
### Contact Folders
159

160
Organize contacts into folders for better management.
161

162
```python { .api }
163
def get_contact_folders(self, limit: int = None) -> list[ContactFolder]:
164
    """
165
    Get contact folders.
166
    
167
    Parameters:
168
    - limit: maximum number of folders to return
169
    
170
    Returns:
171
    - list[ContactFolder]: List of contact folder objects
172
    """
173

174
def get_contact_folder(self, folder_id: str = None, 
175
                      folder_name: str = None) -> ContactFolder:
176
    """
177
    Get a specific contact folder.
178
    
179
    Parameters:
180
    - folder_id: folder identifier
181
    - folder_name: folder display name
182
    
183
    Returns:
184
    - ContactFolder: Contact folder object
185
    """
186

187
def new_contact_folder(self, folder_name: str) -> ContactFolder:
188
    """
189
    Create a new contact folder.
190
    
191
    Parameters:
192
    - folder_name: name for the new folder
193
    
194
    Returns:
195
    - ContactFolder: Created contact folder object
196
    """
197

198
class ContactFolder:
199
    @property
200
    def name(self) -> str:
201
        """Folder display name."""
202
    
203
    @property
204
    def total_item_count(self) -> int:
205
        """Total number of contacts in folder."""
206
    
207
    def get_contacts(self, limit: int = None) -> list[Contact]:
208
        """Get contacts from this folder."""
209
    
210
    def new_contact(self) -> Contact:
211
        """Create a new contact in this folder."""
212
    
213
    def delete(self) -> bool:
214
        """Delete this folder."""
215
```
216

217
### Contact Search and Filtering
218

219
Search and filter contacts based on various criteria.
220

221
```python { .api }
222
def search_contacts(self, search_text: str, limit: int = None) -> list[Contact]:
223
    """
224
    Search for contacts.
225
    
226
    Parameters:
227
    - search_text: text to search for in contact fields
228
    - limit: maximum number of results
229
    
230
    Returns:
231
    - list[Contact]: Matching contacts
232
    """
233

234
# Common filter examples for get_contacts()
235
# By name: display_name__contains='Smith'
236
# By company: company_name='Microsoft'
237
# By email domain: email_addresses__any(lambda x: '@company.com' in x['address'])
238
# Recently created: created_time__gte=datetime(2023, 1, 1)
239
```
240

241
## Usage Examples
242

243
### Basic Contact Operations
244

245
```python
246
from O365 import Account
247

248
account = Account(credentials)
249
address_book = account.address_book()
250

251
# Get all contacts
252
contacts = address_book.get_contacts()
253

254
for contact in contacts:
255
    print(f"Name: {contact.display_name}")
256
    print(f"Company: {contact.company_name}")
257
    if contact.email_addresses:
258
        print(f"Email: {contact.email_addresses[0]['address']}")
259
    print("---")
260
```
261

262
### Create New Contact
263

264
```python
265
# Create a new contact with full information
266
new_contact = address_book.new_contact()
267
new_contact.given_name = "John"
268
new_contact.surname = "Doe"
269
new_contact.display_name = "John Doe"
270
new_contact.company_name = "Acme Corporation"
271
new_contact.job_title = "Software Engineer"
272
new_contact.department = "Engineering"
273

274
# Add contact information
275
new_contact.add_email("john.doe@acme.com", "Work Email", "work")
276
new_contact.add_email("john.personal@gmail.com", "Personal Email", "home")
277

278
new_contact.add_phone("+1-555-123-4567", "work")
279
new_contact.add_phone("+1-555-987-6543", "mobile")
280

281
new_contact.add_address(
282
    street="123 Business St",
283
    city="Seattle",
284
    state="WA",
285
    postal_code="98101",
286
    country="USA",
287
    address_type="work"
288
)
289

290
new_contact.notes = "Met at the tech conference in 2023"
291

292
# Save the contact
293
if new_contact.save():
294
    print(f"Contact created: {new_contact.display_name}")
295
```
296

297
### Contact Folder Management
298

299
```python
300
# Create a folder for work contacts
301
work_folder = address_book.new_contact_folder("Work Contacts")
302

303
# Create a folder for personal contacts
304
personal_folder = address_book.new_contact_folder("Personal")
305

306
# Add contacts to specific folders
307
work_contact = work_folder.new_contact()
308
work_contact.display_name = "Business Partner"
309
work_contact.company_name = "Partner Corp"
310
work_contact.add_email("partner@partnercorp.com")
311
work_contact.save()
312

313
# Get contacts from a specific folder
314
work_contacts = work_folder.get_contacts()
315
print(f"Work contacts: {len(work_contacts)}")
316
```
317

318
### Search and Filter Contacts
319

320
```python
321
# Search for contacts by name
322
johns = address_book.search_contacts("John")
323

324
# Filter contacts by company
325
microsoft_contacts = address_book.get_contacts(
326
    company_name="Microsoft"
327
)
328

329
# Find contacts with specific email domain
330
gmail_contacts = []
331
all_contacts = address_book.get_contacts()
332

333
for contact in all_contacts:
334
    for email in contact.email_addresses:
335
        if "@gmail.com" in email['address']:
336
            gmail_contacts.append(contact)
337
            break
338

339
print(f"Found {len(gmail_contacts)} contacts with Gmail addresses")
340
```
341

342
### Update Existing Contact
343

344
```python
345
# Find and update a contact
346
contact = address_book.search_contacts("John Doe")[0]
347

348
# Update job information
349
contact.job_title = "Senior Software Engineer"
350
contact.department = "Advanced Engineering"
351

352
# Add a new phone number
353
contact.add_phone("+1-555-111-2222", "other")
354

355
# Update notes
356
contact.notes += "\nPromoted to senior engineer in 2023"
357

358
# Save changes
359
if contact.save():
360
    print("Contact updated successfully")
361
```