Send-MgUserMail Graph PowerShell Cmdlet

What is Send-MgUserMail cmdlet?

The Send-MgUserMail cmdlet in Microsoft Graph PowerShell enables administrators and users to send email messages programmatically from a Microsoft 365 mailbox. This cmdlet allows emails to be sent with CC recipients, attachments, and custom internet message headers.

Why use Send-MgUserMail cmdlet?

The Send-MgUserMail cmdlet is useful for:

• Automating email notifications and announcements
• Sending bulk messages with attachments
• Implementing email workflows in automation scripts
• Enhancing security by controlling outbound email communications

Setting Up Microsoft Graph PowerShell

Before using Send-MgUserMail, 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-MgUserMail Cmdlet

The Send-MgUserMail cmdlet sends an email on behalf of the specified user. It allows the inclusion of multiple recipients, CC, attachments, and custom headers.

Cmdlet Syntax

Send-MgUserMail -UserId <String> -BodyParameter <IMicrosoftGraphMessage>

• Send-MgUserMail -UserId <String> -BodyParameter <IMicrosoftGraphMessage>
• -BodyParameter: Defines the message details including recipients, body, and optional parameters such as CC and attachments.

Practical Examples of Send-MgUserMail

Sending Mail with CC

$params = @{
Message = @{
    Subject = "Project Update"
    Body = @{
        ContentType = "Text"
        Content = "Please find the latest update on the project."
    }
    ToRecipients = @(
    @{
        EmailAddress = @{
        Address = "recipient@example.com"
    }
    }
    )
    CcRecipients = @(
        @{
            EmailAddress = @{
            Address = "ccrecipient@example.com"
        }
    }
  )
}
SaveToSentItems = $true
}                                      
Send-MgUserMail -UserId "user@example.com" -BodyParameter $params

Sending Mail with Attachments

$params = @{
Message = @{
    Subject = "Project Documents"
    Body = @{
        ContentType = "Text"
        Content = "Please find the attached documents related to the project."
    }
    ToRecipients = @(
    @{
        EmailAddress = @{
        Address = "recipient@example.com"
    }
    }
    )
    Attachments = @(
    @{
        "@odata.type" = "#microsoft.graph.fileAttachment"
        Name = "ProjectPlan.docx"
        ContentBytes =
        [System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes("C:\Path\To\ProjectPlan.docx"))
    }
    @{
        "@odata.type" = "#microsoft.graph.fileAttachment"
        Name = "Budget.xlsx"
        ContentBytes =
        [System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes("C:\Path\To\Budget.xlsx"))
    }
    )
    }
SaveToSentItems = $true
}
                                            
Send-MgUserMail -UserId "user@example.com" -BodyParameter $params

Sending Mail with Internet Message Headers

$params = @{
Message = @{
    Subject = "Special Announcement"
    Body = @{
        ContentType = "Text"
        Content = "Here is an important announcement."
    }
    ToRecipients = @(
    @{
        EmailAddress = @{
        Address = "recipient@example.com"
    }
    }
    )
    InternetMessageHeaders = @(
    @{
        Name = "X-Custom-Header-1"
        Value = "Custom Value 1"
    }
    @{
        Name = "X-Custom-Header-2"
        Value = "Custom Value 2"
    }
    )
    }
    SaveToSentItems = $true
}
                                            
Send-MgUserMail -UserId "user@example.com" -BodyParameter $params
                                        

Best Practices for Send-MgUserMail

To optimize the use of Send-MgUserMail, 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.
• Secure Attachments: Avoid sending large files; consider linking to OneDrive or SharePoint instead.
• Monitor API Limits: Avoid excessive API calls to prevent throttling.
• Test Before Deployment: Always test email scripts in a non-production environment.

Frequently Asked Questions

1. Can I send emails without saving them to Sent Items using Send-MgUserMail?

Yes, set SaveToSentItems = $false in the request body.

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

Yes, but you need Send As or Send on Behalf permissions.

3. How do I attach multiple files in Send-MgUserMail?

Add multiple objects in the Attachments array within the BodyParameter.

4. How do I troubleshoot permission errors?

Ensure the user has Mail.Send permissions and reauthenticate if needed.

5. What happens if an email fails to send?

Check for invalid recipient addresses or API rate limits.

Possible Errors and Solutions

Error	Cause	Solution
Access Denied	The user does not have Mail.Send permission.	Ensure the correct permissions are granted.
Invalid Recipient Address	The email address provided is incorrect.	Verify the recipient email format
Attachment Too Large	The attachment exceeds the allowed size limit.	Use a file-sharing link instead.
API Rate Limit Exceeded	Too many requests were made in a short period.	Reduce API calls or implement a delay.

Conclusion

The Send-MgUserMail cmdlet is a powerful tool for automating email dispatch in Microsoft 365. By leveraging its features, IT administrators can streamline communication workflows, send notifications, and enhance efficiency in email management.

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