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.

Frequently Asked Questions

• Can I re-send a guest invitation using New-MgInvitation if the user hasn’t responded?

No, once a guest user is created in the directory (even if they haven’t accepted), you cannot re-invite them using New-MgInvitation. You can manually remind the user or remove and re-invite them after deletion.

• How can I confirm if the invited guest has accepted the invitation?

You can use the Get-MgUser cmdlet and filter by the guest’s email. If UserState or SignInActivity.LastSignInDateTime exists, they’ve likely accepted the invitation and accessed resources.

• Can I assign the invited guest to Teams or Groups at the time of invitation?

No, group or team membership must be handled separately using Add-MgGroupMember or Add-MgTeamMember after the user is created.

• What happens if I enter an invalid redirect URL in the invitation?

The guest will be redirected to an invalid or broken page after accepting the invite. Always ensure RedirectUrl points to a valid and user-friendly destination, such as your SharePoint site or Teams landing page.

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.