M365 PowerShell

Using Get-MgUserContact in Graph PowerShell

This guide demonstrates how to use the Get-MgUserContact cmdlet in Microsoft Graph PowerShell to retrieve a user's contacts. Learn how to list all contacts, filter by specific criteria, and export contact details with practical examples.

To retrieve the contacts of a specific user, you can use the Get-MgUserContact cmdlet from the Microsoft Graph PowerShell module. This cmdlet allows you to fetch personal contacts associated with a particular user. Here’s how you can do it:

Retrieving Contacts of a Specific User

The Get-MgUserContact cmdlet retrieves a list of contacts from a specified user’s mailbox. You need the user's user principal name (UPN) or user ID to perform this operation.

Syntax

Get-MgUserContact -UserId <String>

-UserId: The ID or user principal name (UPN) of the user whose contacts you want to retrieve.

Usage Examples

Example 1: Get Contacts for a Specific User

This command retrieves all contacts for the user john.doe@example.com.

Get-MgUserContact -UserId "john.doe@example.com"

Example 2: Get Contacts for a Specific User and Select Specific Properties

This command retrieves contacts for the user john.doe@example.com and selects specific properties to display: DisplayName, EmailAddresses, and BusinessPhones.

Get-MgUserContact -UserId "john.doe@example.com" | Select-Object DisplayName, EmailAddresses, BusinessPhones

Example 3: Export Contacts to a CSV File

To export the contacts of a specific user to a CSV file, you can combine the cmdlet with Export-Csv.

Get-MgUserContact -UserId "john.doe@example.com" | Select-Object DisplayName, EmailAddresses, BusinessPhones | Export-Csv -Path "JohnDoeContacts.csv" -NoTypeInformation

This command retrieves contacts for the user john.doe@example.com, selects specific properties, and exports the result to a CSV file named JohnDoeContacts.csv.

Example 4: Retrieve Contacts Created After a Specific Date (Using -Filter)

Get-MgUserContact supports OData filtering. One useful real-world scenario is identifying recently created contacts.:

                                
Get-MgUserContact -UserId "john.doe@contoso.com" `
  -Filter "createdDateTime ge 2024-01-01T00:00:00Z" `
  -Property "displayName,emailAddresses,createdDateTime"

Example 5: Retrieve Contacts from a Specific Company (Using -Filter with String Match)

                                
Get-MgUserContact -UserId "john.doe@contoso.com" `
  -Filter "companyName eq 'Fabrikam Ltd'" `
  -Property "displayName,emailAddresses,companyName"

Handling Errors

Error: Get-MgUserContact: The remote server returned an error: (403) Forbidden.

Solution: Ensure the account used to run the cmdlet has the necessary permissions to access the user’s contacts. The account should have the appropriate Microsoft Graph permissions, such as Contacts.Read or Contacts.ReadWrite.

Error: Get-MgUserContact: The remote server returned an error: (404) Not Found.

Solution: Verify that the user ID or UPN provided is correct. Ensure the user exists in the Microsoft 365 environment.

Error: Get-MgUserContact: Value cannot be null.

Solution: Ensure that the -UserId parameter is not null or empty. Provide a valid user ID or UPN.

Use Cases

User-Specific Contact Management: Administrators can use this cmdlet to manage and review personal contacts of specific users, especially useful during troubleshooting or audits.
Data Export for Backup: Export user contacts to CSV files for backup purposes or for migration to other systems.
Integration with CRM Systems: Retrieve and synchronize user contacts with customer relationship management (CRM) systems for seamless data integration.

Frequently Asked Questions

1. What is Get-MgUserContact used for?

Get-MgUserContact is a Microsoft Graph PowerShell cmdlet used to retrieve contacts from a user's mailbox, including their display names, email addresses, and phone numbers.

2. Can I filter contacts by their display name?

Yes, use the -Filter parameter to filter by specific properties like display name. Example:

Get-MgUserContact -UserId "<UserPrincipalName>" -Filter "displayName eq 'John Doe'"

3. How can I export contact details to a CSV file?

Use this script to export contact details like display name, email address, and company:

$Contacts = Get-MgUserContact -UserId "<UserPrincipalName>" -All
$Contacts | Select-Object DisplayName, EmailAddresses, CompanyName | Export-Csv -Path "C:\Path\To\UserContacts.csv" -NoTypeInformation

4. What permissions are required to retrieve user contacts?

You need the Contacts.Read or Contacts.ReadWrite permission in Microsoft Graph PowerShell. Ensure appropriate permissions are granted in Azure AD.

Conclusion

The Get-MgUserContact cmdlet is a valuable tool for retrieving personal contacts of specific users in a Microsoft 365 environment. By understanding its syntax, usage examples, and handling potential errors, administrators can efficiently manage user-specific contacts and integrate them with other systems as needed.

Use the Get-MgUserContact cmdlet to enhance your organization's contact management and ensure that your directory is always up-to-date with the latest information.

If You Prefer the Graph API Way

You can retrieve a user's personal contacts stored in Outlook using the Microsoft Graph /users/{userId}/contacts endpoint. This is particularly useful for exporting or filtering personal address books of users in the tenant.

Example 1: Get Contacts for a Specific User
This retrieves all personal contacts for the specified user.

$userId = "john.doe@example.com"
$uri = "https://graph.microsoft.com/v1.0/users/$userId/contacts"

$response = Invoke-MgGraphRequest -Method GET -Uri $uri

foreach ($contact in $response.value) {
    Write-Output "Name  : $($contact.displayName)"
    Write-Output "Email : $($contact.emailAddresses[0].address)"
    Write-Output "`n"
}

✅ Equivalent to:
Get-MgUserContact -UserId "john.doe@example.com"

📘 Docs:
👉 GET /users/{id}/contacts

Example 2: Get Contacts and Select Specific Properties
To reduce payload and focus on specific fields like displayName, emailAddresses, and businessPhones, use the $select query.

$userId = "john.doe@example.com"
$uri = "https://graph.microsoft.com/v1.0/users/$userId/contacts?`$select=displayName,emailAddresses,businessPhones"

$response = Invoke-MgGraphRequest -Method GET -Uri $uri

foreach ($contact in $response.value) {
    Write-Output "Name     : $($contact.displayName)"
    Write-Output "Email    : $($contact.emailAddresses[0].address)"
    Write-Output "Phone(s) : $($contact.businessPhones -join ', ')"
    Write-Output "`n"
}

✅ Equivalent to:
Get-MgUserContact -UserId "john.doe@example.com" | Select DisplayName, EmailAddresses, BusinessPhones

Example 3: Export Contacts to a CSV File
To export contacts to a CSV, retrieve the data, filter it client-side, and save it to disk.

$userId = "john.doe@example.com"
$uri = "https://graph.microsoft.com/v1.0/users/$userId/contacts?`$select=displayName,emailAddresses,businessPhones"

$response = Invoke-MgGraphRequest -Method GET -Uri $uri

$contacts = foreach ($contact in $response.value) {
    [PSCustomObject]@{
        DisplayName     = $contact.displayName
        EmailAddress    = $contact.emailAddresses[0].address
        BusinessPhones  = $contact.businessPhones -join ', '
    }
}

$contacts | Export-Csv -Path "JohnDoeContacts.csv" -NoTypeInformation

✅ Equivalent to:
Get-MgUserContact -UserId "john.doe@example.com" | Select DisplayName, EmailAddresses, BusinessPhones | Export-Csv

Required Permissions

Context	Permission Types
Delegated	`Contacts.Read, Contacts.ReadWrite`
Application	`Contacts.Read, Contacts.ReadWrite`

📘 Related Microsoft Docs

Using Get-MgDirectoryRole in Graph PowerShell
Using Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell