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

Send an HTML Formatted Email

Use this example to send a professional HTML email with formatting, headings, and hyperlinks.


Connect-MgGraph -Scopes "Mail.Send"

$params = @{
    Message = @{
        Subject = "Weekly IT Maintenance Notification"

        Body = @{
            ContentType = "HTML"

            Content = @"
<h2>Scheduled Maintenance</h2>

<p>
The Microsoft 365 environment will undergo maintenance on
<b>Saturday 10 PM</b>.
</p>

<p>
Please save your work before the maintenance window begins.
</p>

<p>
Visit the
<a href='https://m365corner.com'>M365Corner</a>
website for more Microsoft 365 automation guides.
</p>
"@
        }

        ToRecipients = @(
            @{
                EmailAddress = @{
                    Address = "user@domain.com"
                }
            }
        )
    }

    SaveToSentItems = $true
}

Send-MgUserMail `
-UserId "admin@domain.com" `
-BodyParameter $params

What this script does

This script sends an HTML-formatted email using the Send-MgUserMail cmdlet. The email includes headings, bold text, and hyperlinks for better readability.

Why this example is useful

This is useful for:

Sending IT maintenance notifications
Sending formatted announcements
Automated reporting emails
Branding internal communications

Send Email to Multiple Recipients

Use this example to send a single email to multiple users at once.


Connect-MgGraph -Scopes "Mail.Send"
$params = @{
    Message = @{
        Subject = "Security Awareness Reminder"
        Body = @{
            ContentType = "Text"
            Content = "Please complete your mandatory security awareness training before Friday."
        }

        ToRecipients = @(
            @{
                EmailAddress = @{
                    Address = "user1@domain.com"
                }
            },
            @{
                EmailAddress = @{
                    Address = "user2@domain.com"
                }
            },
            @{
                EmailAddress = @{
                    Address = "user3@domain.com"
                }
            }
        )
    }
    SaveToSentItems = $true
}
Send-MgUserMail -UserId "admin@domain.com" -BodyParameter $params

What this script does

This script sends the same email message to multiple recipients using a single Send-MgUserMail request.

Why this example is useful

This is useful for:

Sending organization-wide announcements
Notifying multiple administrators
Sending compliance reminders
Automating bulk internal communication

Tip

For large recipient lists, consider using Microsoft 365 groups or distribution lists instead of manually specifying multiple recipients.

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

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

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

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

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

How do I attach multiple files in Send-MgUserMail?

Add multiple objects in the Attachments array within the BodyParameter.

How do I troubleshoot permission errors?

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

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.

🧾 Use Internet Message Headers for Advanced Email Metadata

You can include custom internet message headers when sending emails using Send-MgUserMail. This is useful for adding tracking data, automation identifiers, or compliance tags.

$params = @{
Message = @{
Subject = "Team Meeting"
Body = @{
    ContentType = "Text"
    Content = "Reminder: Team meeting tomorrow at 10 AM."
}
InternetMessageHeaders = @(
@{
    Name  = "X-Tracking-ID"
    Value = "M365Corner-AutoMailer-001"
}
)
}
SaveToSentItems = $true
}
Send-MgUserMail -UserId "alex@contoso.com" -BodyParameter $params

📧 Automate Email Sending with CSV Input

For bulk communication tasks like user notifications or reminders, automate Send-MgUserMail using a CSV file containing recipient addresses and personalized subjects or messages. This approach is perfect for IT admins who need to reach multiple users efficiently.

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.

New: User Management Graph PowerShell Toolkit

Simplify user tasks like bulk creation, updates, password resets, deletions, license checks, and more — all from one place.

Launch Toolkit