Send-MgUserMessage Graph PowerShell Cmdlet

What is Send-MgUserMessage cmdlet?

The Send-MgUserMessage cmdlet in Microsoft Graph PowerShell enables administrators and users to send email messages from a Microsoft 365 mailbox programmatically. It works in conjunction with the New-MgUserMessage cmdlet, allowing messages to be created as drafts and then sent.

Why use Send-MgUserMessage cmdlet?

The Send-MgUserMessage cmdlet is beneficial for:

• Automating email dispatch for notifications and reminders
• Sending follow-up emails programmatically
• Streamlining bulk email notifications for users
• Reducing manual effort in sending routine messages
• Enhancing security by controlling and automating email workflows

Setting Up Microsoft Graph PowerShell

Before using Send-MgUserMessage, you need to set up Microsoft Graph PowerShell and authenticate with the necessary permissions.

Install the Module

Run the following command to install the Microsoft Graph module:

Install-Module Microsoft.Graph -Scope CurrentUser

This installs the module for the current user without requiring administrative privileges.

Connect to Microsoft Graph

Authenticate and connect to Microsoft Graph with the required permissions:

Connect-MgGraph -Scopes "Mail.Send"

You'll be prompted to sign in using a Microsoft 365 account with the necessary permissions to send emails..

Disconnect After Use

Once you've completed your tasks, always disconnect the session:

Disconnect-MgGraph

This helps maintain security and prevent unnecessary active sessions.

Exploring the Send-MgUserMessage Cmdlet

The Send-MgUserMessage cmdlet is used to send messages that have been created as drafts in a user’s mailbox. It works by specifying the user ID and the message ID of the draft.

Cmdlet Syntax

Send-MgUserMessage -UserId <String> -MessageId <String>

• -UserId: Specifies the sender’s Microsoft 365 user ID.
• -MessageId: Defines the message ID of the draft email that needs to be sent.

Practical Examples of Send-MgUserMessage

Sending a Draft Email

# Create the draft message
$draftMessage = @{
subject = "Reminder: Upcoming Meeting"
body = @{
    contentType = "HTML"
    content = "This is a reminder for your upcoming meeting scheduled for tomorrow at 10 AM."
}
    toRecipients = @(@{ emailAddress = @{ address = "jane.doe@domain.com" } })
}
                                            
# Create the message and retrieve the MessageId
$message = New-MgUserMessage -UserId "john.doe@domain.com" -BodyParameter $draftMessage
                                            
# Send the message
Send-MgUserMessage -UserId "john.doe@domain.com" -MessageId $message.Id
                                        

Sending a Follow-Up Email Automatically

# Create the follow-up draft message
$followUpMessage = @{
subject = "Follow-Up: Action Required"
body = @{                                       
    contentType = "Text"
    content = "Please follow up on the task assigned to you."
}
    toRecipients = @(@{ emailAddress = @{ address = "team.member@domain.com" } })
}
                                            
# Create and send the follow-up message
$message = New-MgUserMessage -UserId "manager@domain.com" -BodyParameter $followUpMessage
Send-MgUserMessage -UserId "manager@domain.com" -MessageId $message.Id
                                        

Sending Bulk Notifications

# Read users from a CSV
$recipients = Import-Csv "recipients.csv"
                                            
foreach ($recipient in $recipients) {
# Create draft for each user
$notificationMessage = @{
subject = "Important Update"
body = @{
    contentType = "Text"
    content = "Please be informed about the recent updates to our policy."
}
    toRecipients = @(@{ emailAddress = @{ address = $recipient.Email } })
}
                                            
# Create and send the message
$message = New-MgUserMessage -UserId "admin@domain.com" -BodyParameter $notificationMessage
Send-MgUserMessage -UserId "admin@domain.com" -MessageId $message.Id
}
                                        

Best Practices for Send-MgUserMessage

To optimize the use of Send-MgUserMessage, follow these best practices:

• Use the Correct API Permissions: Ensure Mail.Send or Mail.ReadWrite permission is granted to avoid authentication errors.
• Validate Recipients: Verify email addresses before sending bulk emails to prevent failures.
• Automate Routine Emails: Schedule automated email dispatches for reports, reminders, and notifications.
• Secure Sensitive Data: Avoid exposing email content or credentials in scripts.
• Monitor API Limits: Avoid excessive API calls to prevent throttling.

Frequently Asked Questions

1. Can I send emails directly without creating a draft using Send-MgUserMessage?

No, Send-MgUserMessage requires a message draft to be created first.

2. Can I send emails from a shared mailbox using Send-MgUserMessage?

Yes, but you need Send As or Send on Behalf permissions for the shared mailbox.

3. How do I check if an email was sent successfully?

Monitor the sent items folder or enable logging to verify successful delivery.

4. What happens if the recipient’s email is incorrect?

Microsoft 365 will generate a non-delivery report (NDR) if the recipient’s address is invalid.

Possible Errors and Solutions

Error	Cause	Solution
Access Denied	The user does not have Mail.Send permission	Ensure the correct permissions are granted.
Invalid Message ID	The message ID provided is incorrect.	Retrieve the correct message ID using New-MgUserMessage
Message Not Sent	API rate limit exceeded or misconfigured parameters.	Check API limits and ensure the correct parameters are used.
User Not Found	Incorrect User ID provided.	Verify the correct User ID using Get-MgUser before sending messages.

Conclusion

The Send-MgUserMessage cmdlet is a powerful tool for automating email dispatch within Microsoft 365. By leveraging its capabilities, IT administrators can streamline email communication, send follow-ups, and manage bulk notifications efficiently.

Follow best practices and troubleshooting steps to ensure smooth and secure email sending using Microsoft Graph PowerShell.