New-MgUserContact

What is New-MgUserContact?

New-MgUserContact is a Microsoft Graph PowerShell cmdlet used to create personal Outlook contacts in a specific user’s mailbox. These contacts are stored in the user’s personal Contacts folder, not in the tenant-wide directory.

Why Use New-MgUserContact?

Administrators use New-MgUserContact to automate mailbox-level contact creation, especially in scenarios like migrations, onboarding, or restoring contacts from backups. It eliminates manual contact entry and enables bulk operations using scripts or CSV files.

Prerequisites

Before using this cmdlet, ensure the following:

• Microsoft Graph PowerShell module installed
• Connected to Microsoft Graph with appropriate permissions

Install-Module Microsoft.Graph -Scope CurrentUser
Connect-MgGraph -Scopes "Contacts.ReadWrite"

How to Use New-MgUserContact?

The cmdlet creates a contact by passing contact properties as a hashtable to the -BodyParameter.
You must specify the UserId (UPN or Object ID) of the mailbox where the contact will be created.

Basic syntax:

New-MgUserContact -UserId $UserId -BodyParameter <Hashtable>

New-MgUserContact 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
                                           

This example creates a single Outlook contact in the specified user’s mailbox.

Example 2: Bulk Contact Addition from CSV

To add multiple contacts, prepare a CSV file named contacts.csv with the following format:

CSV File Formatting

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
                                           

Bulk User Contact Import Script

$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
}
                                           

This script reads contact data from a CSV file and creates contacts in bulk for the specified user.

Summary

Key Point	Details
Cmdlet Name	New-MgUserContact
Purpose	Creates personal Outlook contacts in a user’s mailbox
Required Scope	Contacts.ReadWrite
Target Scope	User mailbox (not tenant-wide directory)
Primary Parameters	UserId, BodyParameter
Automation Benefit	Enables bulk and scripted contact creation
Typical Use Cases	Contact migration, onboarding, restoring mailbox contacts