Immediate answer
Treat this as an integration migration, not a cmdlet rename.
The official PowerShell documentation marks Send-MailMessage obsolete, warns that it does not guarantee secure connections to SMTP servers, and recommends against its use. Microsoft also says there is no immediate replacement available in PowerShell.
This does not mean every historical Send-MailMessage connection lacked TLS, or that every .NET SMTP client is inherently insecure. The actionable fact is that Microsoft has deprecated this cmdlet and does not recommend building a modern Microsoft 365 mail path around it.
The right migration depends on whether the script can change its interface, whether it sends as a user or an application, how credentials are managed, whether SMTP semantics matter, and how failures are observed.
Safe source discovery
Find usage without printing scripts or secrets.
From a controlled repository root, this read-only PowerShell search reports file paths and line numbers containing the cmdlet. It deliberately omits matching line content, which may contain addresses, server names, or unsafe inline credentials.
Get-ChildItem -Path . -Recurse -Filter *.ps1 |
Select-String -Pattern '\bSend-MailMessage\b' |
Select-Object Path, LineNumberExtend the inventory beyond source text. Include scheduled tasks, automation accounts, deployment tooling, backup jobs, monitoring scripts, and scripts generated at runtime. For each caller, record ownership, frequency, recipients, attachments, sender identity, urgency, and what happens when delivery fails.
- 01
Classify business impact
Separate informational reports from password resets, backup failures, security alerts, and other messages whose delay or loss has operational impact.
- 02
Locate credential handling
Find stored passwords, credential files, environment variables, app registrations, managed identities, and interactive assumptions without copying secrets into the inventory.
- 03
Capture delivery semantics
Note HTML, attachments, reply-to, sender impersonation, distribution groups, external recipients, and whether acceptance must survive a temporary outage.
Neutral alternatives
Choose the supported interface the script can own.
Microsoft Graph and Send-MgUserMail
Graph is a strong choice for rewriteable Microsoft 365 automation. The sendMail API supports JSON or MIME and delegated or application Mail.Send permission models. A 202 Accepted response means the request was accepted for processing, not that final delivery is complete.
MailKit or another maintained SMTP library
For software that should retain SMTP and can be engineered, a current library can support explicit TLS and OAuth patterns. Your code still owns token acquisition, Exchange authorization, retry classification, and safe secret handling.
Application-specific notification API
A ticketing, monitoring, workflow, or transactional email service may provide a better supported API than a generic mailbox. Evaluate audit, recipient, data-path, and availability requirements.
Existing organization mail service
An established local MTA or approved SaaS relay may already provide identity, queueing, observability, and policy controls. Reuse it when its service boundary fits.
Local SMTP compatibility bridge
When many stable scripts cannot be rewritten promptly, a local endpoint can preserve their conventional SMTP interface while moving Microsoft-facing authentication into one maintained service.
Conceptual migration patterns
Separate interface choice from identity and reliability.
| Pattern | Best fit | You still own |
|---|---|---|
| Graph from PowerShell | Actively maintained Microsoft 365 automation | App identity, permissions, token handling, Graph errors, and delivery monitoring |
| OAuth SMTP library | Applications where SMTP semantics remain appropriate | Library maintenance, TLS, token lifecycle, Exchange permissions, and retries |
| Local bridge | Many legacy scripts with a stable local SMTP contract | Local trust boundary, sender policy, service operation, and upstream identity |
| Approved service API | Workloads aligned to an existing platform | Vendor governance, API lifecycle, data path, and failure handling |
Do not paste application secrets into examples or source files. Use your organization’s approved identity and secret-management mechanism, apply least privilege, and ensure unattended jobs do not depend on hidden interactive prompts.
Compatibility path
Where RelayBridge fits—and where it does not.
RelayBridge is relevant when a collection of older scripts can continue submitting conventional SMTP to an explicitly authorized local endpoint while a maintained Windows service handles Exchange Online OAuth, durable local queueing, and persisted retries. Messages do not traverse a RelayBridge-operated cloud relay.
This concentrates the compatibility boundary, but it does not eliminate the need to remove embedded credentials, restrict local senders, observe failures, or decide which scripts should eventually be rewritten. Read the SMTP OAuth architecture guide and how RelayBridge separates the two hops.
This compatibility path is provided by an independent project, not by Microsoft. Its public MPL-2.0 source allows administrators to inspect the implementation directly; it is not a Microsoft certification or endorsement.
For one maintainable script, a clean Graph/API migration is often simpler. Native OAuth-capable software, an approved notification platform, or an existing suitable mail service may also remove any need for RelayBridge.
Migration checklist
Retire the obsolete dependency without hiding mail failures.
- 01
Build a script and owner inventory
Search repositories and automation hosts, then classify business impact and maintenance ownership.
- 02
Select a per-workload target
Use Graph, a current SMTP library, an application API, an existing mail service, or a compatibility bridge according to the actual requirement.
- 03
Design identity before code
Choose delegated or application access, least-privilege permissions, secret or certificate lifecycle, and unattended execution behavior.
- 04
Preserve failure visibility
Capture request or SMTP responses, queue state, retries, correlation identifiers, and operator alerts. A successful API call is not proof of inbox delivery.
- 05
Remove obsolete paths and secrets
After parallel validation, disable old credentials, remove dead parameters, and keep an inventory check in code review or CI.
Clarifications
Frequently asked questions.
Is Send-MgUserMail a drop-in replacement?
No. It uses Microsoft Graph, which has a different identity, permissions, message model, response behavior, and error surface from SMTP.
Does 202 Accepted mean the message was delivered?
No. Microsoft documents that it means the Graph request was accepted for processing. Exchange transport and policy processing still follow.
Must every script move to Graph?
No. Graph is one legitimate option. A maintained SMTP library, application API, existing mail service, or local compatibility bridge can be appropriate depending on the workload.
Authoritative sources