Using Remove-MgUserContact in Graph PowerShell

The Remove-MgUserContact cmdlet is a powerful tool within the Graph PowerShell module that allows administrators to delete user contacts from their Microsoft 365 environment. This article delves into the cmdlet's syntax, provides practical usage examples, offers tips and solutions for potential errors, and outlines key use cases.

Cmdlet Syntax

The basic syntax for the Remove-MgUserContact cmdlet is as follows:

Remove-MgUserContact -UserId <String> -ContactId <String> [<CommonParameters>]

• -UserId: Specifies the user ID (either the user principal name or the user's unique identifier).
• -ContactId: Specifies the contact ID to be removed.
• <CommonParameters>: Includes common parameters like -Verbose, -Debug, etc.

Usage Examples

Remove a Specific Contact for a User:

Remove-MgUserContact -UserId "john.doe@contoso.com" -ContactId "AAMkADkzZjk3ODk3LTgxMjQtNDI1NC1hYzBiLWZhM2Y4MTY1NzNlYwBGAAAAAABBbbQxofVsQqcQEAAAAAAA="

In this example, a specific contact for user "john.doe@contoso.com" is removed using the contact's unique ID.

Verbose Mode for Detailed Output:

Remove-MgUserContact -UserId "jane.doe@contoso.com" -ContactId "AAMkADkzZjk3ODk3LTgxMjQtNDI1NC1hYzBiLWZhM2Y4MTY1NzNlYwBGAAAAAABBbbQxofVsQqcQEAAAAAAA=" -Verbose

Using the -Verbose parameter provides detailed output useful for troubleshooting and confirming the contact removal process.

Bulk Removal of Contacts for a User:

$contactsToRemove = @("ContactId1", "ContactId2", "ContactId3")
$userId = "john.doe@contoso.com"

foreach ($contactId in $contactsToRemove) {
    Remove-MgUserContact -UserId $userId -ContactId $contactId
}

This example demonstrates how to remove multiple contacts for a single user by iterating over an array of contact IDs.

Note: How to Get the Contact ID

To obtain the contact ID for the contact to be deleted, use the Get-MgUserContact cmdlet. This cmdlet retrieves the list of contacts for a specified user, allowing you to identify and select the contact IDs needed for removal.

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

Cmdlet Tips

• Identify Contacts to Remove: Before removing a contact, use the Get-MgUserContact cmdlet to list user contacts and obtain the necessary contact IDs.
• Automation Scripts: Combine Get-MgUserContact and Remove-MgUserContact in scripts to automate the cleanup of outdated or irrelevant contacts across multiple users.

Use Cases

1. Cleaning Up Outdated or Inactive Contacts:
• Scenario: Over time, users may accumulate outdated or inactive contacts, such as old vendors, former employees, or contacts that are no longer relevant.
• Implementation: Use Remove-MgUserContact to automate the cleanup of these inactive contacts, ensuring that only current and relevant contacts remain in the directory.
• Benefit: Helps keep the contact list clean and up to date, reducing clutter and improving the efficiency of communication by eliminating unnecessary contacts from the address book.


2. Removing Duplicate Contacts from User Mailboxes::
• Scenario: Duplicate contacts can arise when users accidentally save the same person’s information multiple times, leading to confusion during communication.
• Implementation: Use Get-MgUserContact to identify duplicate contacts based on attributes like email address or display name, and then remove the duplicates with Remove-MgUserContact.
• Benefit: Improves the accuracy and clarity of a user's contact list, ensuring that there are no redundant or duplicate entries, and making it easier to manage communications.


3. Automating Contact Removal After Business Engagements End:
• Scenario: Organizations often have temporary business engagements with clients or contractors, after which their contact details should be removed to avoid any confusion or unnecessary data retention.
• Implementation: Use Remove-MgUserContact to automatically delete contacts associated with expired contracts or concluded projects, based on predefined criteria such as end dates or labels.
• Benefit: Helps ensure that business contacts are only retained for as long as necessary, improving data privacy and reducing the risk of retaining outdated information in the system.


4. Managing Contact Lists for Shared Mailboxes:
• Scenario: Shared mailboxes, used by teams or departments, can accumulate numerous contacts over time. These contacts may need to be regularly updated or removed to ensure the mailbox remains relevant and organized.
• Implementation: Use Remove-MgUserContact to periodically review and remove old or irrelevant contacts from shared mailboxes, ensuring that the contact list remains efficient and up-to-date for team members.
• Benefit: Enhances the overall management of shared mailboxes by ensuring that contacts remain relevant and useful for everyone using the shared resource, reducing clutter and improving team efficiency.

Frequently Asked Questions

• Can I recover a deleted contact using Microsoft Graph?

No. Once a contact is deleted using Remove-MgUserContact, it is permanently removed. There’s no restore option in Graph PowerShell for contacts.

• Does this cmdlet delete contacts from Outlook or the Global Address List (GAL)?

Remove-MgUserContact deletes contacts from a user’s personal Outlook mailbox, not from the organization’s Global Address List.

• Can I delete multiple contacts at once?

Yes. You can retrieve a list of contacts with Get-MgUserContact and pipe the results into Remove-MgUserContact in a loop for bulk deletions.

• What permission is required to use Remove-MgUserContact?

You need the Contacts.ReadWrite permission (delegated or application-based) in Microsoft Graph to delete user contacts successfully.

Possible Errors & Solutions

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

Connect-MgGraph -Scopes "Contacts.ReadWrite"

Conclusion

The Remove-MgUserContact cmdlet is an essential tool for administrators managing Microsoft 365 environments. It ensures the removal of unnecessary or outdated contacts, contributing to better organization and security. By understanding the cmdlet's syntax, exploring practical examples, and addressing potential errors, administrators can effectively use this cmdlet to maintain clean and efficient contact lists.

For more information and detailed documentation, visit the official Microsoft documentation.

If You Prefer the Graph API Way

Note: Microsoft Graph API allows you to delete user contacts via the /users/{userId}/contacts/{contactId} endpoint. Below are examples using Invoke-MgGraphRequest.

1. Remove a Specific Contact for a User

# Replace with actual UserId (UPN or ID) and ContactId
$userId    = "john.doe@contoso.com"
$contactId = "AAMkADkzZjk3ODk3LTgxMjQtNDI1NC1hYzBiLWZhM2Y4MTY1NzNlYwBGAAAAAABBbbQxofVsQqcQEAAAAA"

$uri = "https://graph.microsoft.com/v1.0/users/$userId/contacts/$contactId"

Invoke-MgGraphRequest -Method DELETE -Uri $uri
                                

✅ Equivalent to:
Remove-MgUserContact -UserId "john.doe@contoso.com" -ContactId "<id>"

2. Bulk Removal of Contacts for a User

# Replace with actual UserId and contact IDs
$userId = "john.doe@contoso.com"
$contactsToRemove = @(
    "AAMkADkzZjk3ODk3LTgxMjQtNDI1NC1hYzBiLWZhM2Y4MTY1NzNlYwBGAAAAAA1",
    "AAMkADkzZjk3ODk3-LTgxMjQtNDI1LC0yYzBiLWZhM2Y4MTY1NzNlYwBGAAAAAA2",
    "AAMkADkzZjk3ODk3LTgxMjQtNDI1LC0xYzBiLWZhM2Y4MTY1NzNlYwBGAAAAAA3"
)

foreach ($contactId in $contactsToRemove) {
    $uri = "https://graph.microsoft.com/v1.0/users/$userId/contacts/$contactId"
    Invoke-MgGraphRequest -Method DELETE -Uri $uri
}
                                

✅ Equivalent to using a looped version of Remove-MgUserContact Ideal for administrators needing to clean up contact records in batch.

3. Required Permissions

You’ll need one of the following permissions:

• Delegated: Contacts.ReadWrite
• Application: Contacts.ReadWrite

Graph API Documentation

• 👉 DELETE /users/{user-id}/contacts/{contact-id}

Related Articles: