How to Use Send-MgUserMail to Send Microsoft 365 Mails?

Need to send emails programmatically from a Microsoft 365 account using PowerShell? Whether it's for automation, alerts, or sending reports with attachments, the Send-MgUserMail cmdlet from Microsoft Graph PowerShell is your go-to solution.

This guide shows you how to use Send-MgUserMail with real-world examples to send emails—including CCs, attachments, and even custom headers.

What is Send-MgUserMail?

Send-MgUserMail is a Microsoft Graph PowerShell cmdlet that allows you to send emails from a specified Microsoft 365 user account. It uses the Microsoft Graph API and supports text/HTML content, attachments, CC/BCC recipients, and internet message headers.

Why Use Send-MgUserMail?

Here are just a few reasons to consider this cmdlet:

• Send emails as part of automated workflows or scheduled jobs
• Attach files like logs, reports, or documents
• Customize headers or include CC/BCC for communication control
• No need for Outlook client or SMTP—works directly with Microsoft 365 accounts

Cmdlet Syntax

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

• UserId: The user who is sending the email (typically their UPN or ID)
• BodyParameter: A hashtable that defines the message structure, recipients, content, attachments, etc.

Usage Examples

Example 1: 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
                                          

Example 2: 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
                                          

Example 3: 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
                                          

Frequently Asked Questions

• Can I send HTML emails using this cmdlet?
  Yes! Just set ContentType = "HTML" in the body section.
• Is SaveToSentItems mandatory?
  No, but it's recommended. Set it to $true if you want the email to appear in the sender’s Sent Items.
• Can I send emails as another user?
  Only if you have proper permissions—like Mail.Send or Mail.Send.Shared—and the mailbox allows delegated access.
• Can I add BCC recipients?
  Yes. Use the BccRecipients property like you do with ToRecipients or CcRecipients.

Use Cases

• Automated Reports: Email system health or security reports daily.
• User Notifications: Trigger messages when a task is completed or an account is created.
• Compliance Alerts: Notify admins or users when sensitive actions are performed.
• Custom Workflows: Integrate with PowerShell scripts that require follow-up communication.

Conclusion

The Send-MgUserMail cmdlet is a powerful tool for administrators and developers who want to automate Microsoft 365 communications. It supports everything from simple alerts to rich, attachment-filled messages and is perfect for integrating into scheduled scripts and workflows.

Whether you're sending a daily report or a compliance alert—Send-MgUserMail gets the message across!