Using New-MgUserContact in Graph PowerShell

This guide demonstrates how to use the New-MgUserContact cmdlet in Microsoft Graph PowerShell to create new contacts for a user. Learn how to add single or multiple contacts with practical examples.

The New-MgUserContact cmdlet is part of the Microsoft Graph PowerShell module, allowing administrators to create new contacts in their Microsoft 365 environment. This cmdlet is essential for managing personal contacts programmatically, especially when dealing with bulk operations or automating contact creation.

Cmdlet Syntax

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

New-MgUserContact -UserId $UserId -BodyParameter 

• -UserId: This parameters specifies the UserId for whom the contact is going to be created.
• -BodyParameter: This parameter specifies the properties of the contact to be created. It accepts a hashtable or a custom object containing contact details such as GivenName, Surname, EmailAddresses, etc.

Usage Examples

Example 1: Creating a Single Contact

$contact = @{
    GivenName = "John"
    Surname = "Doe"
    EmailAddresses = @(
        @{
            Address = "john.doe@example.com"
            Name = "John Doe"
        }
    )
    BusinessPhones = @("123-456-7890")
    MobilePhone = "098-765-4321"
    CompanyName = "Contoso"
}

New-MgUserContact -UserId “user@example.com” -BodyParameter $contact

In this example, a new contact named John Doe is created with specified email addresses and phone numbers for the user user@example.com and becomes available in the user's address book.

Note: You can check whether contact got added by running Get-MgUserContact. The newly added contact should appear in the list.

Example 2: Bulk Contact Addition from CSV

To add multiple contacts in bulk, you can use a CSV file with the required contact details. Prepare the CSV file (contacts.csv) with the following headers: GivenName, Surname, Email, BusinessPhone, MobilePhone, CompanyName

Example:

GivenName,Surname,Email,BusinessPhone,MobilePhone,CompanyName
John,Doe,john.doe@example.com,123-456-7890,098-765-4321,Contoso
Jane,Smith,jane.smith@example.com,234-567-8901,123-456-7890,Fabrikam

Use the following script to read the CSV file and create contacts:

$contacts = Import-Csv -Path "contacts.csv"

foreach ($contact in $contacts) {
    $contactParams = @{
        GivenName = $contact.GivenName
        Surname = $contact.Surname
        EmailAddresses = @(
            @{
                Address = $contact.Email
                Name = "$($contact.GivenName) $($contact.Surname)"
            }
        )
        BusinessPhones = @($contact.BusinessPhone)
        MobilePhone = $contact.MobilePhone
        CompanyName = $contact.CompanyName
    }

    New-MgUserContact -UserId “user@example.com” -BodyParameter $contactParams
}

Possible Errors & Solutions

Error: "New-MgUserContact: Cannot bind parameter 'BodyParameter' to the target."

Solution: Ensure the -BodyParameter is correctly structured as a hashtable or custom object. Verify that all required fields are included and correctly spelled.

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

Solution: This error typically occurs due to insufficient permissions. Ensure that the account running the cmdlet has the necessary permissions to create contacts in Microsoft 365.

Error: "New-MgUserContact: The remote server returned an error: (400) Bad Request."

Solution: Verify the format and content of the contact details. Ensure that email addresses and phone numbers are in valid formats.

Use Cases

• Automating Contact Creation: Organizations can automate the creation of contacts for new employees, partners, or customers, ensuring up-to-date and accurate contact lists.
• Bulk Operations: The cmdlet is highly useful for bulk operations, such as importing contacts from legacy systems or other data sources into Microsoft 365.
• Integration with HR Systems: Integrate with HR management systems to automatically add new hires' contact details to the organization's directory.

Frequently Asked Questions

1. What is New-MgUserContact used for?

New-MgUserContact is a Microsoft Graph PowerShell cmdlet used to add new contacts to a user’s mailbox, including properties like name, email, and phone numbers.

2. Can I specify additional contact properties?

Yes, you can include other properties like businessPhones or companyName in the body parameter.

$Body = @{
    displayName = "Jane Doe"
    emailAddresses = @(@{address = "janedoe@example.com"})
    businessPhones = @("987-654-3210")
    companyName = "Contoso Ltd"
}
New-MgUserContact -UserId "<UserPrincipalName>" -BodyParameter $Body
                            

3. What permissions are required to create contacts?

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

Conclusion

The New-MgUserContact cmdlet is a powerful tool for administrators looking to manage contacts within their Microsoft 365 environment efficiently. With its ability to handle bulk operations and automation, it can save time and reduce the potential for human error. By understanding its syntax, usage examples, and handling potential errors, administrators can leverage this cmdlet to streamline their contact management processes.

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

Related Articles: