New-MgInvitation: Inviting External Users to Microsoft 365 Tenant

The New-MgInvitation cmdlet in Microsoft Graph PowerShell is used to invite external users (guests) to your Microsoft 365 tenant. This cmdlet enables secure collaboration by generating invitations and granting access to specific resources.

Cmdlet Syntax

New-MgInvitation -InvitedUserEmailAddress <String> -InvitedUserDisplayName <String> -InviteRedirectUrl <String> -SendInvitationMessage -InvitedUserMessageInfo <Hashtable>

Key Parameters:

• -InvitedUserEmailAddress: Email address of the guest user.
• -InvitedUserDisplayName: Display name of the guest user.
• -InviteRedirectUrl: The URL users are directed to after accepting the invitation.
• -SendInvitationMessage: Sends an invitation email to the user.
• -InvitedUserMessageInfo: Optional customized message for the user.

Usage Examples

Example 1: Single Guest User Creation

Invite a single external user by specifying their email address and display name.

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.Invite.All"

# Invite a single guest user
New-MgInvitation -InvitedUserEmailAddress "henry@contoso.com" `
                 -InvitedUserDisplayName "Henry Adams" `
                 -InviteRedirectUrl "https://portal.office.com" `
                 -SendInvitationMessage `
                 -InvitedUserMessageInfo @{customizedMessageBody = "Welcome to our organization!"}

Verify the invitation using:

Get-MgUser -Filter "Mail eq 'henry@contoso.com'"

Example 2: Bulk Guest User Creation via CSV

Use a CSV file to invite multiple external users at once. The CSV should have the following structure:

Email,DisplayName,Message
henry@contoso.com,Henry Adams,Welcome to Contoso!
julia@fabrikam.com,Julia Smith,Please review the documents shared with you.

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.Invite.All"

# Path to the CSV file
$csvPath = "path_to_your_csv_file.csv"

# Import the CSV file
$guestUsers = Import-Csv -Path $csvPath

foreach ($guestUser in $guestUsers) {
    $guestUserEmail = $guestUser.Email
    $invitedUserDisplayName = $guestUser.DisplayName
    $invitedUserMessage = $guestUser.Message

    $invitation = New-MgInvitation -InvitedUserEmailAddress $guestUserEmail `
                                   -InvitedUserDisplayName $invitedUserDisplayName `
                                   -InviteRedirectUrl "https://portal.office.com" `
                                   -SendInvitationMessage `
                                   -InvitedUserMessageInfo @{customizedMessageBody = $invitedUserMessage}

    if ($invitation.Status -eq "PendingAcceptance") {
        Write-Output "Invitation sent successfully to $guestUserEmail"
    } else {
        Write-Output "Failed to send invitation to $guestUserEmail"
    }
}

Verify the list of guest users:

Get-MgUser -Filter "UserType eq 'Guest'"

Cmdlet Tips

• Always use the -InviteRedirectUrl parameter to specify the landing page after acceptance.
• The -InvitedUserMessageInfo parameter is optional, but adding a custom message enhances communication.
• To troubleshoot invitation errors, ensure the guest's email domain is allowed in your Azure AD external collaboration settings.

Possible Errors & Solutions

Error	Cause	Solution
Authentication_Required	Not authenticated to Microsoft Graph.	Use Connect-MgGraph -Scopes "User.Invite.All" to authenticate.
Request_BadRequest	Missing or invalid parameter.	Ensure all required parameters are provided and correctly formatted.
InvalidDomain	Guest email domain blocked.	Check Azure AD external collaboration policies to allow the guest domain.
UserInvitationFailed	Invitation could not be sent.	Ensure the email address is valid and check tenant restrictions.

Use Cases

• Collaborating with External Partners: Share access to files, Teams, or applications with external stakeholders.
• Bulk Guest Management: Automate inviting multiple external users for large-scale projects.
• Custom Onboarding Messages: Provide tailored instructions or welcome messages during the invitation process.

Conclusion

The New-MgInvitation cmdlet streamlines guest user management in Microsoft 365 by automating the invitation process. Whether inviting a single user or multiple users in bulk, this cmdlet enhances collaboration while maintaining security. For administrators, leveraging this cmdlet ensures an efficient and organized approach to managing external users.